timor.task.Goals ================ .. py:module:: timor.task.Goals Classes ------- .. autoapisummary:: timor.task.Goals.At timor.task.Goals.Follow timor.task.Goals.GoalBase timor.task.Goals.GoalWithDuration timor.task.Goals.Pause timor.task.Goals.Reach timor.task.Goals.ReturnTo Module Contents --------------- .. py:class:: At(ID, goalPose, constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.At :parts: 1 :private-bases: A goal that is achieved when the robot is at a certain position for at least one time step t. The robot does not need to be still standing, though. Pass a desired pose :param ID: The id of the goal. This is used to identify the goal in the solution. :param goalPose: The goal pose to be reached. :param constraints: A list of constraints that need to be satisfied for the goal to be achieved. .. py:method:: __eq__(other) At goals are same if they have the same constraints and desired pose .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) Returns true, if the solution satisfies this goal. :param solution: Any solution instance that must contain a time at which this goal was solved :return: True if the end effector placement at time t is within the defined tolerances for the desired pose .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:method:: _valid(solution, t_goal, idx_goal) Checks all goal-level constraints .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Loads the At goal to a dictionary description. .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: goal_pose :type: timor.utilities.tolerated_pose.ToleratedPose .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:property:: nominal_goal The nominal goal pose .. py:method:: to_json_data() Dumps the At goal to a dictionary description. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:method:: visualize(viz, scale = 0.33, show_name = False) Shows an error pointing towards the desired position .. py:class:: Follow(ID, trajectory, external_forces = None, external_torques = None, force_torque_reference_frame = 'world', constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.Follow :parts: 1 :private-bases: This goal is achieved if the robot follows a prescribed end-effector trajectory. Follow a given trajectory. :param ID: The goal ID :param trajectory: The trajectory to follow (a sequence of desired poses) :param external_forces: An external force to be applied to the robot during execution of the goal :param external_torques: An external torque to be applied to the robot during execution of the goal :param force_torque_reference_frame: The reference frame in which forces/torques are expressed :param constraints: Goal-level constraints .. py:method:: __eq__(other) Two follow goals are equal if they have the same duration, trajectory and constraints. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) Implements check if goal achieved at claimed time :note: Side-effect if desired trajectory is not timed: Will set `self.duration` such that the trajectory is followed in the time-interval [t_goal-duration, t_goal]. This allows constraint checking in _valid to know all time-steps within this goal. .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:attribute:: _duration .. py:attribute:: _external_forces :type: numpy.ndarray :value: None .. py:attribute:: _external_torques :type: numpy.ndarray :value: None .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:attribute:: _trajectory :type: timor.utilities.trajectory.Trajectory .. py:method:: _valid(solution, t_goal, idx_goal) A goal with duration needs to ensure that its constraints hold at all time-steps within this duration. .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:attribute:: epsilon :type: float :value: 1e-09 .. py:attribute:: force_torque_reference_frame :type: Optional[str] :value: 'world' .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Loads the Follow goal from a dictionary description. .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: get_time_range_goal(solution) Get all time-steps in solution that belong to this goal's duration as list of times and indices. :param solution: Solution to evaluate this goal with duration on. :returns: - A tuple of times that are included in the duration of the goal - A range of indices into the solution's time array that fall into the duration of this goal .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:method:: to_json_data() Dumps the Follow goal to a dictionary description. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:property:: trajectory :type: timor.utilities.trajectory.Trajectory The trajectory to follow along .. py:method:: visualize(viz, *, scale = 0.33, num_markers = 2, show_name = False) Shows the follow goal with num_markers triads to show desired orientation. :param num_markers: How many triads to display along the desired trajectory (2 = show at start and end of trajectory) .. py:property:: wrench :type: numpy.ndarray The external wrench applied to the end effector .. py:class:: GoalBase(ID, constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.GoalBase :parts: 1 :private-bases: The base implementation for a task goal. Initiate goals with the according parameters :param ID: The id of the goal. This is used to identify the goal in the solution. :param constraints: A list of constraints that need to be satisfied for the goal to be achieved - but only here. (Which separates them from task goals which must hold for a whole task) .. py:method:: __eq__(other) :abstractmethod: Enforce the implementation .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) :abstractmethod: Needs to be implemented by children according to the goal .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:method:: _valid(solution, t_goal, idx_goal) Checks all goal-level constraints .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: :abstractmethod: Deserializes a goal from a dictionary .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:method:: to_json_data() :abstractmethod: Returns a json-compatible dictionary representation of the goal. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:method:: visualize(viz, scale = 0.33, show_name = False) :abstractmethod: Every goal should have a visualization. The default color is green. :param viz: A meshcat visualizer as defined in pinocchio :param scale: The visualization method assumes the robot size is ~1-2m maximum reach. Use the scale factor to adapt for significantly different sizes of robots and/or obstacles. :param show_name: Whether to show the name of the goal in the visualization. .. py:class:: GoalWithDuration(ID, duration, constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.GoalWithDuration :parts: 1 :private-bases: Any goal that needs to test more than a single time-step to be achieved. This also includes checking the goal constraints at any point of the goal's duration. Construct a goal with duration. .. py:method:: __eq__(other) :abstractmethod: Enforce the implementation .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) :abstractmethod: Needs to be implemented by children according to the goal .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:attribute:: _duration .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:method:: _valid(solution, t_goal, idx_goal) A goal with duration needs to ensure that its constraints hold at all time-steps within this duration. .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:attribute:: epsilon :type: float :value: 1e-09 .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: :abstractmethod: Deserializes a goal from a dictionary .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: get_time_range_goal(solution) Get all time-steps in solution that belong to this goal's duration as list of times and indices. :param solution: Solution to evaluate this goal with duration on. :returns: - A tuple of times that are included in the duration of the goal - A range of indices into the solution's time array that fall into the duration of this goal .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:method:: to_json_data() :abstractmethod: Returns a json-compatible dictionary representation of the goal. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:method:: visualize(viz, scale = 0.33, show_name = False) :abstractmethod: Every goal should have a visualization. The default color is green. :param viz: A meshcat visualizer as defined in pinocchio :param scale: The visualization method assumes the robot size is ~1-2m maximum reach. Use the scale factor to adapt for significantly different sizes of robots and/or obstacles. :param show_name: Whether to show the name of the goal in the visualization. .. py:class:: Pause(ID, duration, constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.Pause :parts: 1 :private-bases: This goal is achieved if the robot does not move for a preconfigured duration. Construct a goal with duration. .. py:method:: __eq__(other) Two pause goals are equal if there's (almost) the same pause and constraints. .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) Returns true, if the robot does not move for a preconfigured duration, starting at t_goal. .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:attribute:: _duration .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:method:: _valid(solution, t_goal, idx_goal) A goal with duration needs to ensure that its constraints hold at all time-steps within this duration. .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:property:: duration :type: float Getter for explicit duration of Pause Goal. .. py:attribute:: epsilon :type: float :value: 1e-09 .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Loads the Pause goal from a dictionary description. .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: get_time_range_goal(solution) Get all time-steps in solution that belong to this goal's duration as list of times and indices. :param solution: Solution to evaluate this goal with duration on. :returns: - A tuple of times that are included in the duration of the goal - A range of indices into the solution's time array that fall into the duration of this goal .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:method:: to_json_data() Dumps the Pause goal to a dictionary description. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:method:: visualize(viz, scale = 0.33, show_name = False) Pause goals cannot be visualized, but the method is kept for consistency .. py:class:: Reach(ID, goalPose, velocity_tolerance = Tolerance.Abs6dPoseTolerance.default(), constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.Reach :parts: 1 :private-bases: A goal that is achieved when the robot is at a certain position for at least one time step at zero velocity Reach a desired pose while standing still. :param ID: The id of the goal. This is used to identify the goal in the solution. :param goalPose: The goal pose to be reached. :param velocity_tolerance: Defines the velocity tolerance for v_desired. :param constraints: A list of constraints that need to be satisfied for the goal to be achieved. .. py:method:: __eq__(other) Reach goals are same if they have the same constraints, velocity, and desired pose .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) Returns true, if position and velocity are within the defined tolerances .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:method:: _valid(solution, t_goal, idx_goal) Checks all goal-level constraints .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Loads the Reach goal to a dictionary description. .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: goal_pose :type: timor.utilities.tolerated_pose.ToleratedPose .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:property:: nominal_goal The nominal goal pose .. py:method:: to_json_data() Dumps the Reach goal to a dictionary description. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:attribute:: velocity_tolerance .. py:method:: visualize(viz, scale = 0.33, show_name = False) Shows an error pointing towards the desired position .. py:class:: ReturnTo(ID, returnToGoal = None, epsilon = 0.0001, constraints = None) .. autoapi-inheritance-diagram:: timor.task.Goals.ReturnTo :parts: 1 :private-bases: This goal is achieved when the robot returns to the state it was in at a previous goal Return to a previous goal :param ID: The id of the goal. This is used to identify the goal in the solution. :param returnToGoal: ID of other goal which should be matched again; can be left out to denote the start of the solution trajectory. :param epsilon: Allowed L2 distance between joint states at this goal and the the other goal. .. py:method:: __eq__(other) Return goals are same if they have the same constraints, tolerance, and return to option .. py:method:: __getstate__() Return objects which will be pickled and saved. .. py:method:: __hash__() Hashes the goal by its id .. py:method:: __setstate__(state) Take object from parameter and use it to retrieve class state. .. py:attribute:: __slots__ :value: () .. py:method:: _achieved(solution, t_goal, idx_goal) Returns true, if position, velocity and acceleration are (almost) equal to those at t=return_to_t .. py:method:: _assert_constraints_local() Checks that the constraints of this goal have a "local meaning". :raises: ValueError if one of the constraints would be better off as a global constraint. .. py:method:: _constraints_serialized() .. py:method:: _deduce_package_dir(filepath, content) :staticmethod: Logic for deducing the package directory if the JSONable object is loaded from a file. :param filepath: The path to the file. :param content: The content of the file parsed into a dictionary. :note: This method can be overridden by subclasses to provide custom package directory resolution; e.g. Task.py. .. py:method:: _get_t_idx_goal(solution) Finds the time t and the index within the time array idx at which the goal is achieved. .. py:attribute:: _id :value: '' .. py:method:: _valid(solution, t_goal, idx_goal) Checks all goal-level constraints .. py:method:: achieved(solution) Calls the custom _achieved method and checks that constraints are held .. py:attribute:: constraints :value: None .. py:attribute:: desired_pose :type: Optional[timor.utilities.tolerated_pose.ToleratedPose] :value: None .. py:attribute:: distance_tolerance .. py:method:: from_json_data(d, *args, **kwargs) :classmethod: Loads the Return goal to a dictionary description. .. py:method:: from_json_file(filepath, *args, **kwargs) :classmethod: Factory method to load a class instance from a json file. :param filepath: The path to the json file. :param args: Additional arguments to pass to the from_json_data factory method of the specific class. :param kwargs: Additional arguments to pass to the from_json_data factory method of the specific class. .. py:method:: from_json_string(s, *args, **kwargs) :classmethod: Create from a json string. .. py:method:: goal_from_json_data(description, frames) :staticmethod: Maps a json description to a goal instance .. py:attribute:: green_material .. py:property:: id :type: str The unique goal identifier .. py:attribute:: return_to_goal :value: None .. py:method:: to_json_data() Dumps the Return goal to a dictionary description. .. py:method:: to_json_file(save_at, *args, **kwargs) Writes the instance to a json file. :param save_at: File location or folder to write the class to. .. py:method:: to_json_string() Return the json string representation. .. py:method:: visualize(viz, scale = 0.33, show_name = False) Shows an error pointing towards the desired position