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, liket1
,t2
for time orx1
,x2
for space.Each class that inherits from
Bounds
should define adata
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 printingprimary_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 BoundsThe
Bounds
class comes with acombine
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 acast
mechanism to recast predicates to use other dimensions. Thecast
mechanism takes in a function that expects one or moredict
-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
, andx2
: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 functionp'
. It expectsp
to take in some amount ofdict
-like objects and re-map lookups in those objects according toschema
.In particular, let
obj
be an argument top
. Then for every keyk
inschema
,obj[k]
will be re-mapped toobj[schema[k]]
inp'
. .. rubric:: ExampleLet’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 keyk
inschema
,k
is re-mapped toschema[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
andother
) 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 toNone
, which uses theprimary_axis
ofself
.Returns: The size of the bounds across some axis.
-
to_json
()¶ Converts the bounds to a JSON object.
-