rekall.bounds.abstract_bounds module¶

This module defines the Bounds class, which all bounds should inherit from.

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