rekall.bounds.bounds3D module

This module defines and implements the Bounds3D three-dimensional bound.

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