Frame¶

class georges_core.frame.Frame(parent: Optional[georges_core.frame.Frame] = None, reference: Optional[georges_core.frame.Frame] = None)[source]¶

Bases: object

A Frame object represents a reference frame for affine geometry transformations (rotations and translations). It has full support for transformation chaining through the notion of ‘parent frame’ and is able to provide rotation angles and translation offsets with respect to any parent among the linked list of parents.

Additionnally Frames are unit-aware through the use of ‘pint quantities’. The internal representations use the ‘quaternion-numpy’ module with the base units being radians and meters. This is transparent to the public interface which can use arbitrary units for the representations of lengths and angles.

Frame handles quaternion rotations via quaternion-numpy: https://github.com/moble/quaternion .

>>> f1 = Frame()
>>> f1.translate_y(10 * _ureg.cm) 
<zgoubidoo.frame.Frame object at 0x...>
>>> f2 = Frame(parent=f1)
>>> f2.parent == f1
True
>>> f2.translate_x(1 * _ureg.cm) 
<zgoubidoo.frame.Frame object at 0x...>
>>> f2.get_origin(f1)
[<Quantity(0.01, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.o == f2.origin == f2.get_origin(None)
True

Initialize a Frame with respect to a parent frame. If no parent is provided the newly created frame is considered to be a global reference frame. The frame is create with no rotation or translate with respect to its parent frame.

Parameters

parent – parent frame, if None then the frame itself is considered as a global reference frame.
reference – reference frame, all quantities are provided by default with respect to this frame.
allows to use the properties easily but can be modified on a case-by-case basis for each function. (This) –
the reference frame can be modified after the object creation. (Alternatively) –

Attributes Summary

`angles`	Examples
`o`	Offset of the frame with respect to a reference frame.
`o_`	Provides the offset representing the translation of the frame with respect to another reference frame.
`origin`	Offset of the frame with respect to a reference frame.
`origin_`	Provides the offset representing the translation of the frame with respect to another reference frame.
`parent`	Provides the parent frame.
`q`	Provides the quaternion representation of the rotation of the frame with respect to another reference frame.
`quaternion`	Provides the quaternion representation of the rotation of the frame with respect to another reference frame.
`reference`	Provides the reference frame with respect to which the quantities will be provided.
`tx`	Examples
`ty`	Examples
`tz`	Examples
`x`	X axis offset with respect to a reference frame.
`x_`	X axis offset with respect to a reference frame (internal units).
`y`	Y axis offset with respect to a reference frame.
`y_`	Provides the Y axis offset representing the translation of the frame with respect to another reference frame.
`z`	Provides the Z axis offset representing the translation of the frame with respect to another reference frame.
`z_`	Provides the Z axis offset representing the translation of the frame with respect to another reference frame.

Methods Summary

`get_angles`([ref, units])	Examples
`get_euler_angles`([ref])	param ref
`get_origin`([ref])	Offset of the frame with respect to a reference frame.
`get_quaternion`([ref])	Provides the quaternion representation of the rotation of the frame with respect to another reference frame.
`get_rotation_matrix`([ref])	Provides the rotation matrix representation of the quaternion with respect to another reference frame.
`get_rotation_vector`([ref])	param ref
`get_tx`([ref])	Examples
`get_ty`([ref])	Examples
`get_tz`([ref])	Examples
`get_x`([ref])	X axis offset with respect to a reference frame.
`get_y`([ref])	Y axis offset with respect to a reference frame.
`get_z`([ref])	Provides the Z axis offset representing the translation of the frame with respect to another reference frame.
`reset`()	Reset the frame.
`rotate`(angles)	Examples
`rotate_axis`(axis, angle)	Examples
`rotate_x`(angle)	Examples
`rotate_y`(angle)	Examples
`rotate_z`(angle)	Examples
`translate`(offset)	Translates the origin of the Frame with respect to the parent reference frame.
`translate_axis`(axis, offset)	Example
`translate_x`(offset)	Examples
`translate_y`(offset)	Examples
`translate_z`(offset)	Example

Attributes Documentation

angles¶

Examples

>>> f1 = Frame() # TODO

Parameters

ref –
units –

Returns:

o¶

Offset of the frame with respect to a reference frame.

Provides the offset representing the translation of the frame with respect to another reference frame. This method supports units and returns pint quantities with dimensions of [LENGTH].

Parameters: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the global reference frame.
Returns: the offset (list of quantities with dimensions of [LENGTH]) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(0.0, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]

o_¶

Provides the offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Parameters: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the current reference frame.

Retunrs:: the offset (numpy array, no units) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1._get_origin()
array([0.1, 0. , 0. ])
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2._get_origin()
array([0.1, 1. , 0. ])
>>> f2._get_origin(f1)
array([0., 1., 0.])

origin¶

Offset of the frame with respect to a reference frame.

Provides the offset representing the translation of the frame with respect to another reference frame. This method supports units and returns pint quantities with dimensions of [LENGTH].

Parameters: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the global reference frame.
Returns: the offset (list of quantities with dimensions of [LENGTH]) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(0.0, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]

origin_¶

Provides the offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Parameters: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the current reference frame.

Retunrs:: the offset (numpy array, no units) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1._get_origin()
array([0.1, 0. , 0. ])
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2._get_origin()
array([0.1, 1. , 0. ])
>>> f2._get_origin(f1)
array([0., 1., 0.])

parent¶

Provides the parent frame.

Returns: parent frame, None in case the frame is a global reference frame.

Examples

>>> f1 = Frame()
>>> f1.parent is None
True
>>> f2 = Frame(parent=f1)
>>> f2.parent == f1
True

The ‘parent’ property can also be set:

>>> f1 = Frame()
>>> f1.parent is None
True
>>> f2 = Frame()
>>> f2.parent is None
True
>>> f2.parent = f1
>>> f2.parent is f1
True
>>> f2.parent == f1
True
>>> f2.parent = None
>>> f2.parent is None
True

q¶

Provides the quaternion representation of the rotation of the frame with respect to another reference frame.

Parameters: ref – reference frame with respect to which the rotation quaternion is returned. If None then the rotation is provided with respect to the current reference frame.
Returns: the quaternion representing the rotation with respect to a given reference frame.

Examples

>>> f1 = Frame().rotate_z(20 * _ureg.degree)
>>> f1.get_quaternion()
quaternion(0.984807753012208, 0, 0, 0.17364817766693)
>>> f2 = Frame(f1)
>>> f2.rotate_x(10 * _ureg.degree).get_quaternion() 
quaternion(0.981060..., 0.085831..., 0.015134..., 0.172987...)
>>> f2.get_quaternion(f1) 
quaternion(0.996194..., 0.087155..., 0, 0)

quaternion¶

Provides the quaternion representation of the rotation of the frame with respect to another reference frame.

Parameters: ref – reference frame with respect to which the rotation quaternion is returned. If None then the rotation is provided with respect to the current reference frame.
Returns: the quaternion representing the rotation with respect to a given reference frame.

Examples

>>> f1 = Frame().rotate_z(20 * _ureg.degree)
>>> f1.get_quaternion()
quaternion(0.984807753012208, 0, 0, 0.17364817766693)
>>> f2 = Frame(f1)
>>> f2.rotate_x(10 * _ureg.degree).get_quaternion() 
quaternion(0.981060..., 0.085831..., 0.015134..., 0.172987...)
>>> f2.get_quaternion(f1) 
quaternion(0.996194..., 0.087155..., 0, 0)

reference¶

Provides the reference frame with respect to which the quantities will be provided. None if not set.

Returns: a frame serving as reference frame for the current frame (None if not set)

Examples

>>> f1 = Frame(parent=None, reference=None)
>>> f1.reference is None
True
>>> f2 = Frame(parent=f1, reference=f1)
>>> f2.reference is f1
True
>>> f2.reference == f1
True
>>> f2.reference = None
>>> f2.reference is None
True

tx¶

Examples

>>> f1 = Frame() # TODO

Parameters: ref –

Returns:

ty¶

Examples

>>> f1 = Frame() # TODO

Parameters: ref –

Returns:

tz¶

Examples

>>> f1 = Frame() # TODO

Parameters: ref –

Returns:

x¶

X axis offset with respect to a reference frame.

Provides the X axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_x()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_x()
<Quantity(0.1, 'meter')>
>>> f2.get_x(f1)
<Quantity(0.0, 'meter')>

Parameters: ref – reference frame with respect to which the origin is returned.

If None then the translation is provided with respect to the current reference frame.

Returns: the X axis offset (with units, pint quantity) representing the X axis translation with respect to a given reference frame.

x_¶

X axis offset with respect to a reference frame (internal units).

Provides the X axis offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Parameters

ref – reference frame with respect to which the origin is returned.
None then the translation is provided with respect to the current reference frame. (If) –

Returns

the X axis offset (float, no units) representing the X axis translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1._get_x()
0.1
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2._get_x()
0.1
>>> f2._get_x(f1)
0.0

y¶

Y axis offset with respect to a reference frame.

Provides the Y axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

Examples

>>> f1 = Frame().translate_y(10 * _ureg.cm)
>>> f1.get_y()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_y()
<Quantity(0.1, 'meter')>
>>> f2.get_y(f1)
<Quantity(0.0, 'meter')>

Parameters

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
respect to the current reference frame. (with) –

Returns

the Y axis offset (with units, pint quantity) representing the Y axis translation with respect to

a given reference frame.

y_¶

Provides the Y axis offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

>>> f1 = Frame().translate_y(10 * _ureg.cm)
>>> f1._get_y()
0.1
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2._get_y()
0.1
>>> f2._get_y(f1)
0.0

Parameters

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
respect to the current reference frame. (with) –

Returns

the Y axis offset (float, no units) representing the Y axis translation with respect to a given reference frame.

z¶

Provides the Z axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_z(10 * _ureg.cm)
>>> f1.get_z()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_z()
<Quantity(0.1, 'meter')>
>>> f2.get_z(f1)
<Quantity(0.0, 'meter')>

Parameters

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
respect to the current reference frame. (with) –

Returns

the Z axis offset (with units, pint quantity) representing the Z axis translation with respect to a given reference frame.

z_¶

Provides the Z axis offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Examples

>>> f1 = Frame().translate_z(10 * _ureg.cm)
>>> f1._get_z()
0.1
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2._get_z()
0.1
>>> f2._get_z(f1)
0.0

Parameters

ref – reference frame with respect to which the origin is returned.
None then the translation is provided with respect to the current reference frame. (If) –

Returns

the Z axis offset (float, no units) representing the Z axis translation with respect to a given reference frame.

Methods Documentation

get_angles(ref: Optional[georges_core.frame.Frame] = None, units: pint.unit.build_unit_class.<locals>.Unit = <Unit('radian')>) → List[pint.quantity.build_quantity_class.<locals>.Quantity][source]¶

Examples

>>> f1 = Frame() # TODO

Parameters

ref –
units –

Returns:

get_euler_angles(ref: Optional[georges_core.frame.Frame] = None) → numpy.ndarray[source]¶

Parameters: ref –

Returns:

get_origin(ref: Optional[georges_core.frame.Frame] = None) → List[pint.quantity.build_quantity_class.<locals>.Quantity][source]¶

Offset of the frame with respect to a reference frame.

Provides the offset representing the translation of the frame with respect to another reference frame. This method supports units and returns pint quantities with dimensions of [LENGTH].

Parameters: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the global reference frame.
Returns: the offset (list of quantities with dimensions of [LENGTH]) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(0.0, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]

get_quaternion(ref: Optional[georges_core.frame.Frame] = None) → quaternion.quaternion[source]¶

Provides the quaternion representation of the rotation of the frame with respect to another reference frame.

Parameters: ref – reference frame with respect to which the rotation quaternion is returned. If None then the rotation is provided with respect to the current reference frame.
Returns: the quaternion representing the rotation with respect to a given reference frame.

Examples

>>> f1 = Frame().rotate_z(20 * _ureg.degree)
>>> f1.get_quaternion()
quaternion(0.984807753012208, 0, 0, 0.17364817766693)
>>> f2 = Frame(f1)
>>> f2.rotate_x(10 * _ureg.degree).get_quaternion() 
quaternion(0.981060..., 0.085831..., 0.015134..., 0.172987...)
>>> f2.get_quaternion(f1) 
quaternion(0.996194..., 0.087155..., 0, 0)

get_rotation_matrix(ref: Optional[georges_core.frame.Frame] = None) → numpy.ndarray[source]¶

Provides the rotation matrix representation of the quaternion with respect to another reference frame.

Example

>>> f1 = Frame().rotate_x(10 * _ureg.degree).get_rotation_matrix()
1.0

Parameters: ref – reference frame with respect to which the rotation matrix is returned
Returns: the rotation matrix representation of the quaternion

get_rotation_vector(ref: Optional[georges_core.frame.Frame] = None) → numpy.ndarray[source]¶

Parameters: ref –

Returns:

get_tx(ref: Optional[georges_core.frame.Frame] = None) → pint.quantity.build_quantity_class.<locals>.Quantity[source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: ref –

Returns:

get_ty(ref: Optional[georges_core.frame.Frame] = None) → pint.quantity.build_quantity_class.<locals>.Quantity[source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: ref –

Returns:

get_tz(ref: Optional[georges_core.frame.Frame] = None) → pint.quantity.build_quantity_class.<locals>.Quantity[source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: ref –

Returns:

get_x(ref: Optional[georges_core.frame.Frame] = None) → pint.quantity.build_quantity_class.<locals>.Quantity[source]¶

X axis offset with respect to a reference frame.

Provides the X axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_x()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_x()
<Quantity(0.1, 'meter')>
>>> f2.get_x(f1)
<Quantity(0.0, 'meter')>

Parameters: ref – reference frame with respect to which the origin is returned.

If None then the translation is provided with respect to the current reference frame.

Returns: the X axis offset (with units, pint quantity) representing the X axis translation with respect to a given reference frame.

get_y(ref: Optional[georges_core.frame.Frame] = None) → pint.quantity.build_quantity_class.<locals>.Quantity[source]¶

Y axis offset with respect to a reference frame.

Provides the Y axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

Examples

>>> f1 = Frame().translate_y(10 * _ureg.cm)
>>> f1.get_y()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_y()
<Quantity(0.1, 'meter')>
>>> f2.get_y(f1)
<Quantity(0.0, 'meter')>

Parameters

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
respect to the current reference frame. (with) –

Returns

the Y axis offset (with units, pint quantity) representing the Y axis translation with respect to

a given reference frame.

get_z(ref: Optional[georges_core.frame.Frame] = None) → pint.quantity.build_quantity_class.<locals>.Quantity[source]¶

Provides the Z axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_z(10 * _ureg.cm)
>>> f1.get_z()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_z()
<Quantity(0.1, 'meter')>
>>> f2.get_z(f1)
<Quantity(0.0, 'meter')>

Parameters

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
respect to the current reference frame. (with) –

Returns

the Z axis offset (with units, pint quantity) representing the Z axis translation with respect to a given reference frame.

reset() → georges_core.frame.Frame [source]¶

Reset the frame.

Reset the frame (rotation and translation) with respect to the parent; the frame is thus equivalent to its parent frame.

Examples

>>> f1 = Frame().rotate_x(1 * _ureg.radian)
>>> f1.get_angles() 
[<Quantity(0.0, 'radian')>, <Quantity(0.999..., 'radian')>, <Quantity(0.999..., 'radian')>]
>>> f1.reset().get_angles()
[<Quantity(0.0, 'radian')>, <Quantity(0.0, 'radian')>, <Quantity(0.0, 'radian')>]

Returns: the reseted frame itself (to allow method chaining).

rotate(angles: List[pint.quantity.build_quantity_class.<locals>.Quantity]) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: angles –
Returns: the rotated frame (in place), allows method chaining

rotate_axis(axis: str, angle: float) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters

axis –
angle –

Returns:

rotate_x(angle: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: angle –

Returns:

rotate_y(angle: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: angle –

Returns:

rotate_z(angle: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: angle –

Returns:

translate(offset: List[pint.quantity.build_quantity_class.<locals>.Quantity]) → georges_core.frame.Frame [source]¶

Translates the origin of the Frame with respect to the parent reference frame. The translations are extrinsic (done with respect to the axes of the parent frame).

Examples

>>> f1 = Frame()
>>> f1.translate([1.0 * _ureg.meter, 2.0 * _ureg.meter, 3.0 * _ureg.meter]).o
[<Quantity(1.0, 'meter')>, <Quantity(2.0, 'meter')>, <Quantity(3.0, 'meter')>]
>>> f2 = Frame(parent=f1)
>>> f2.translate([-1.0 * _ureg.meter, -2.0 * _ureg.meter, -3.0 * _ureg.meter]).o
[<Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(-1.0, 'meter')>, <Quantity(-2.0, 'meter')>, <Quantity(-3.0, 'meter')>]
>>> f2.rotate_x(180 * _ureg.degree).o
[<Quantity(0.0, 'meter')>, <Quantity(4.0, 'meter')>, <Quantity(6.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(-1.0, 'meter')>, <Quantity(-2.0, 'meter')>, <Quantity(-3.0, 'meter')>]

Parameters: offset – a list representing the offset (elements of the list must be quantities of dimension [LENGTH])
Returns: the translated frame (in place), allows method chaining

translate_axis(axis: str, offset: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Example

>>> f1 = Frame() # TODO

Parameters

axis –
offset –

Returns

the translated frame (in place)

translate_x(offset: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: offset –

Returns:

translate_y(offset: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Examples

>>> f1 = Frame() # TODO

Parameters: offset –

Returns:

translate_z(offset: pint.quantity.build_quantity_class.<locals>.Quantity) → georges_core.frame.Frame [source]¶

Example

>>> f1 = Frame() # TODO

Parameters: offset –
Returns: the translated frame (in place)