pycram.designator

Module Contents

Classes

Designator	Implementation of designators. DEPRECTAED SINCE DESIGNATOR DESCRIPTIONS ARE USED AS BASE CLASS
DesignatorDescription	ivar resolve: The resolver function to use for this designator, defaults to self.ground
ActionDesignatorDescription	Abstract class for action designator descriptions.
LocationDesignatorDescription	Parent class of location designator descriptions.
ObjectDesignatorDescription	Class for object designator descriptions.

Attributes

SPECIAL_KNOWLEDGE

exception pycram.designator.DesignatorError(*args, **kwargs)

Bases: Exception

Implementation of designator errors.

Create a new designator error.

exception pycram.designator.ResolutionError(missing_properties: typing_extensions.List[str], wrong_type: typing_extensions.Dict, current_type: typing_extensions.Any, designator: Designator)

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

class pycram.designator.Designator(description: DesignatorDescription, parent: typing_extensions.Optional[Designator] = None)

Bases: abc.ABC

Implementation of designators. DEPRECTAED SINCE DESIGNATOR DESCRIPTIONS ARE USED AS BASE CLASS

Designators are objects containing sequences of key-value pairs. They can be resolved which means to generate real parameters for executing actions from these pairs of key and value.

Variables:

timestamp – The timestamp of creation of reference or None if still not referencing an object.

Create a new desginator.

Arguments: :param description: A list of tuples (key-value pairs) describing this designator. :param parent: The parent to equate with (default is None).

resolvers

List of all designator resolvers. Designator resolvers are functions which take a designator as argument and return a list of solutions. A solution can also be a generator.

equate(parent: Designator) → None

Equate the designator with the given parent.

Arguments: parent – the parent to equate with.

equal(other: Designator) → bool

Check if the designator describes the same entity as another designator, i.e. if they are equated.

Arguments: other – the other designator.

first() → Designator

Return the first ancestor in the chain of equated designators.

current() → Designator

Return the newest designator, i.e. that one that has been equated last to the designator or one of its equated designators.

_reference() → typing_extensions.Any

This is a helper method for internal usage only.

This method is to be overwritten instead of the reference method.

reference() → typing_extensions.Any

Try to dereference the designator and return its data object or raise DesignatorError if it is not an effective designator.

abstract next_solution()

Return another solution for the effective designator or None if none exists. The next solution is a newly constructed designator with identical properties that is equated to the designator since it describes the same entity.

solutions(from_root: typing_extensions.Optional[Designator] = None)

Return a generator for all solutions of the designator.

Arguments: from_root – if not None, the generator for all solutions beginning from with the original designator is returned (default is None).

copy(new_properties: typing_extensions.Optional[typing_extensions.List] = None) → Designator

Construct a new designator with the same properties as this one. If new properties are specified, these will be merged with the old ones while the new properties are dominant in this relation.

Arguments: new_properties – a list of new properties to merge into the old ones (default is None).

make_effective(properties: typing_extensions.Optional[typing_extensions.List] = None, data: typing_extensions.Optional[typing_extensions.Any] = None, timestamp: typing_extensions.Optional[float] = None) → Designator

Create a new effective designator of the same type as this one. If no properties are specified, this ones are used.

Arguments: new_properties – a list of properties (default is None). data – the low-level data structure the new designator describes (default is None). timestamp – the timestamp of creation of reference (default is the current).

newest_effective() → Designator

Return the newest effective designator.

prop_value(key: str) → typing_extensions.Any

Return the first value matching the specified property key.

Arguments: key – the key to return the value of.

check_constraints(properties: typing_extensions.List) → bool

Return True if all the given properties match, False otherwise.

Arguments: properties – the properties which have to match. A property can be a tuple in which case its first value is the key of a property which must equal the second value. Otherwise it’s simply the key of a property which must be not None.

make_dictionary(properties: typing_extensions.List) → typing_extensions.Dict

DEPRECATED, Moved to the description. Function only keept because of backward compatability. Return the given properties as dictionary.

Arguments: properties – the properties to create a dictionary of. A property can be a tuple in which case its first value is the dictionary key and the second value is the dictionary value. Otherwise it’s simply the dictionary key and the key of a property which is the dictionary value.

rename_prop(old: str, new: str) → Designator

class pycram.designator.DesignatorDescription(resolver: typing_extensions.Optional[typing_extensions.Callable] = None)

Bases: abc.ABC

Variables:

resolve – The resolver function to use for this designator, defaults to self.ground

Create a Designator description.

Parameters:

resolver – The grounding method used for the description. The grounding method creates a location instance that matches the description.

make_dictionary(properties: typing_extensions.List[str])

Creates a dictionary of this description with only the given properties included.

Parameters:

properties – A list of properties that should be included in the dictionary. The given properties have to be an attribute of this description.

Returns:

A dictionary with the properties as keys.

ground() → typing_extensions.Any

Should be overwritten with an actual grounding function which infers missing properties.

get_slots() → typing_extensions.List[str]

Returns a list of all slots of this description. Can be used for inspecting different descriptions and debugging.

Returns:

A list of all slots.

copy() → DesignatorDescription

class pycram.designator.ActionDesignatorDescription(resolver=None)

Bases: DesignatorDescription, pycram.language.Language

Abstract class for action designator descriptions. Descriptions hold possible parameter ranges for action designators.

Create a Designator description.

Parameters:

resolver – The grounding method used for the description. The grounding method creates a location instance that matches the description.

class Action

The performable designator with a single element for each list of possible parameter.

robot_position: pycram.datastructures.pose.Pose

The position of the robot at the start of the action.

robot_torso_height: float

The torso height of the robot at the start of the action.

robot_type: pycram.datastructures.enums.ObjectType

The type of the robot at the start of the action.

__post_init__()

abstract perform() → typing_extensions.Any

Executes the action with the single parameters from the description.

abstract to_sql() → pycram.orm.action_designator.Action

Create an ORM object that corresponds to this description.

Returns:

The created ORM object.

insert(session: sqlalchemy.orm.session.Session, *args, **kwargs) → pycram.orm.action_designator.Action

Add and commit this and all related objects to the session. Auto-Incrementing primary keys and foreign keys have to be filled by this method.

Parameters:

• session – Session with a database that is used to add and commit the objects

• args – Possible extra arguments

• kwargs – Possible extra keyword arguments

Returns:

The completely instanced ORM object

abstract ground() → Action

Fill all missing parameters and chose plan to execute.

__iter__()

Iterate through all possible actions fitting this description

Yield:

A resolved action designator

class pycram.designator.LocationDesignatorDescription(resolver=None)

Bases: DesignatorDescription

Parent class of location designator descriptions.

Create a Designator description.

Parameters:

resolver – The grounding method used for the description. The grounding method creates a location instance that matches the description.

class Location

Resolved location that represents a specific point in the world which satisfies the constraints of the location designator description.

pose: pycram.datastructures.pose.Pose

The resolved pose of the location designator. Pose is inherited by all location designator.

abstract ground() → Location

Find a location that satisfies all constrains.

pycram.designator.SPECIAL_KNOWLEDGE

class pycram.designator.ObjectDesignatorDescription(names: typing_extensions.Optional[typing_extensions.List[str]] = None, types: typing_extensions.Optional[typing_extensions.List[pycram.datastructures.enums.ObjectType]] = None, resolver: typing_extensions.Optional[typing_extensions.Callable] = None)

Bases: DesignatorDescription

Class for object designator descriptions. Descriptions hold possible parameter ranges for object designators.

Base of all object designator descriptions. Every object designator has the name and type of the object.

Parameters:

• names – A list of names that could describe the object

• types – A list of types that could represent the object

• resolver – An alternative resolver that returns an object designator for the list of names and types

class Object

A single element that fits the description.

property pose

Property of the current position and orientation of the object. Evaluate the _pose function.

Returns:

Position and orientation

name: str

Name of the object

obj_type: pycram.datastructures.enums.ObjectType

Type of the object

world_object: typing_extensions.Optional[pycram.world_concepts.world_object.Object]

Reference to the World object

_pose: typing_extensions.Optional[typing_extensions.Callable]

A callable returning the pose of this object. The _pose member is used overwritten for data copies which will not update when the original world_object is moved.

__post_init__()

to_sql() → pycram.orm.object_designator.Object

Create an ORM object that corresponds to this description.

Returns:

The created ORM object.

insert(session: sqlalchemy.orm.session.Session) → pycram.orm.object_designator.Object

Add and commit this and all related objects to the session. Auto-Incrementing primary keys and foreign keys have to be filled by this method.

Parameters:

session – Session with a database that is used to add and commit the objects

Returns:

The completely instanced ORM object

frozen_copy() → ObjectDesignatorDescription

Returns a copy of this designator containing only the fields.

Returns:

A copy containing only the fields of this class. The WorldObject attached to this pycram object is not copied. The _pose gets set to a method that statically returns the pose of the object when this method was called.

__repr__()

Return repr(self).

special_knowledge_adjustment_pose(grasp: str, pose: pycram.datastructures.pose.Pose) → pycram.datastructures.pose.Pose

Returns the adjusted target pose based on special knowledge for “grasp front”.

Parameters:

• grasp – From which side the object should be grasped

• pose – Pose at which the object should be grasped, before adjustment

Returns:

The adjusted grasp pose

ground() → typing_extensions.Union[Object, bool]

Return the first object from the world that fits the description.

Returns:

A resolved object designator

__iter__() → typing_extensions.Iterable[Object]

Iterate through all possible objects fitting this description

Yield:

A resolved object designator