rekall.bounds package¶

Submodules¶

rekall.bounds.utils module

Module contents¶

This module defines Bounds, Bounds1D, and Bounds3D. These classes define the core functionality underlying temporal and spatiotemporal bounds in Intervals.

class rekall.bounds.Bounds¶

Bases: abc.ABC

The Bounds class is a simple wrapper around a dictionary. Typically, the keys in this dictionary should represent physical bounds, like t1, t2 for time or x1, x2 for space.

Each class that inherits from Bounds should define a data dict upon initialization. This allows fields from the bounds to be referenced using [] notation.

Each child class should also implement the following methods:

__lt__ for sorting

__repr__ for printing

primary_axis to specify a tuple representing the major axis for optimization. For videos, the primary will typically be ('t1', 't2').

copy for producing a copy of this Bounds

The Bounds class comes with a combine method that takes two Bounds instances and a combiner function and combines them into one Bounds. Child classes may want to implement common combination functions or provide mechanisms to use different combination functions across multiple axes.

The Bounds class also provides a cast mechanism to recast predicates to use other dimensions. The cast mechanism takes in a function that expects one or more dict-like objects as input and remaps keys of the input.

Example

Let’s define a simple function that prints the ‘t’ field of an object:

def print_t(obj):
    print(obj['t'])

Now suppose we have an object with a key of ‘x’ instead:

my_obj = { 'x': 1 }

Then we can cast print_t to print out the ‘x’ field instead of the ‘t’ field:

>>> cast({'t': 'x'})(print_t)(my_obj)
1

See the example below for a full example of a Bounds class.

Example

The example below defines a two-dimensional Bounds object with two dimensions, defined by t1, t2, x1, and x2:

from rekall.predicates import overlaps

class Bounds2D(Bounds):
    def __init__(self, t1, t2, x1, x2):
        self.data = { 't1': t1, 't2': t2, 'x1': x1, 'x2': x2 }

    def __lt__(self, other):
        return ((self['t1'], self['t2'], self['x1'], self['x2']) <
                (other['t1'], other['t2'], other['x1'], other['x2']))

    def __repr__(self):
        return 't1:{} t2:{} x1:{} x2:{}'.format(
            self['t1'], self['t2'], self['x1'], self['x2'])

    def primary_axis(self):
        return ('t1', 't2')

    def T(pred):
        return cast({ 't1': 'x1', 't2': 'x2' })(pred)

bounds1 = Bounds2D(0, 1, 0.5, 0.7)
bounds2 = Bounds2D(2, 3, 0.4, 0.6)

# overlaps expects two objects with fields 't1' and 't2' and
#   computes whether there is overlap in that dimension

# This is False, since there is no time overlap
overlaps()(bounds1, bounds2)

# This is True, since there is overlap in the X dimension
Bounds2D.X(overlaps())(bounds1, bounds2)

# This is True.
bounds1 < bounds2

# This returns ('t1', 't2')
bounds1.primary_axis()

data¶: dict mapping from co-ordinate keys to co-ordinate values

cast()¶

Return a function that takes in a predicate function and remaps key lookups according to schema.

The output function takes in a predicate function p and returns a modified function p'. It expects p to take in some amount of dict-like objects and re-map lookups in those objects according to schema.

In particular, let obj be an argument to p. Then for every key k in schema, obj[k] will be re-mapped to obj[schema[k]] in p'. .. rubric:: Example

Let’s define a simple function that prints the ‘t’ field of an object:

def print_t(obj):
    print(obj['t'])

Now suppose we have an object with a key of ‘x’ instead::: my_obj = { ‘x’: 1 }

Then we can cast print_t to print out the ‘x’ field instead of the ‘t’ field:

>>> cast({'t': 'x'})(print_t)(my_obj)
1

Parameters:	schema – A `dict` representing re-mappings for the target function. For every key `k` in `schema`, `k` is re-mapped to `schema[k]` in the transformed function.
Returns:	A function that transforms a predicate function by remapping key-value lookups in the predicate function’s arguments.

combine(other, combiner)¶

Combines two Bounds into a single new Bound using combiner.

Parameters:	other – The other Bound to combine with. combiner – A function that takes two Bounds as input (`self` and `other`) and returns a single new Bound.
Returns:	The output of `combiner(self, other)`.

copy()¶: Method to get another Bound that has the same data as this Bound. Child classes should implement this.

primary_axis()¶: Method to get the primary axis of a Bound for optimizations. Child classes should implement this.

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`.
Returns:	The size of the bounds across some axis.

to_json()¶: Converts the bounds to a JSON object.

class rekall.bounds.Bounds1D(t1, t2)¶

Bases: rekall.bounds.abstract_bounds.Bounds

Object representing a one-dimensional (temporal) bound.

This class has co-ordinates ‘t1’ and ‘t2’, representing the start and end in a temporal dimension, respectively. This class has no built-in casts, since there’s only one dimension.

T()¶: Returns a tuple representing the time axis.

copy()¶: Returns a copy of this bound.

classmethod fromTuple(t1t2_tuple)¶

Create a Bounds1D object with a tuple of length two.

Parameters:	t1t2_tuple – A tuple of length two. The tuple items can be any type with an ordering function. The first tuple item becomes the value for ‘t1’, and the second tuple item becomes the value for ‘t2’.
Returns:	A Bounds1D object with ‘t1’ and ‘t2’ co-ordinates, specified by `t1t2_tuple`.

intersect(other)¶

Returns the bound intersecting self and other, or None if the bounds do not overlap.

Returns:	A single Bounds1D covering the intersection of `self` and `other`, or `None` if the two bounds do not overlap.

primary_axis()¶: The primary axis is time.

span(other)¶

Returns the minimum Bound spanning both self and other.

Returns:	A single Bounds1D spanning `self` and `other`.

class rekall.bounds.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.