rekall.bounds package¶
Submodules¶
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:
object
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.
-
-
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
andother
, orNone
if the bounds do not overlap.Returns: A single Bounds1D covering the intersection of self
andother
, orNone
if the two bounds do not overlap.
-
primary_axis
()¶ The primary axis is time.
-
span
(other)¶ Returns the minimum Bound spanning both
self
andother
.Returns: A single Bounds1D spanning self
andother
.
-
-
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()
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.
-