Introduce Action and SceneState

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Added `compas_fab.planning` that contains `Action` classes and `SceneState`
+* Added `RoboticAction`, `LinearMotion`, `FreeMotion`, `OpenGripper`, `CloseGripper`, `ManualWorkpieceMotion`, `HideWorkpieces` and `ShowWorkpieces`.
+* Added `SceneState` as container for `WorkpieceState`, `ToolState` and `RobotState`.
+
 ### Changed
 
 * `CollisionMesh` now inherit from `compas.data.Data`

docs/api/compas_fab.planning.rst

@@ -0,0 +1,2 @@
+
+.. automodule:: compas_fab.planning

src/compas_fab/__init__.py

@@ -12,15 +12,27 @@
 Robots
 ------
 
-The core features are located in the ``robots`` module with the specific backend
-implementations in the ``backends`` modules:
+Features for modeling robots and methods to perform static inverse kinematics and
+single-action motion planning.
+The user-facing features are located in the ``robots`` module.
+The implementations of planning backends are located in the ``backends`` modules:
 
 .. toctree::
     :maxdepth: 1
 
     compas_fab.robots
     compas_fab.backends
 
+Planning
+--------
+
+Features for modeling multi-action robotic processes and methods for planning them.
+
+.. toctree::
+    :maxdepth: 1
+
+    compas_fab.planning
+
 CAD integration
 ---------------
 

src/compas_fab/planning/__init__.py

@@ -0,0 +1,107 @@
+"""
+********************************************************************************
+compas_fab.planning
+********************************************************************************
+
+.. currentmodule:: compas_fab.planning
+
+This package contains data classes for modeling robotic process and algorithms for planning robotic motions.
+The current implementation supports single-robot (:class:`compas_fab.robots.Robot`)
+processes with one or more workpieces (:class:`Workpiece`) and tools (:class:`compas_fab.robots.Tool`).
+The processes contains actions that are assumed to be sequentially executed by the robot
+or by the operator (manually). Concurrent actions are not supported.
+
+The FabricationProcess class and its subclasses (such as :class:`PickAndPlaceProcess` and
+:class:`ExtrusionProcess`) are used to model a process. They provide helper methods for
+creating a ordered list of actions that are used for planning and execution. The beining of the
+process is defined by the initial state of the scene, which is a container for the state of all
+objects in the scene (see :class:`SceneState`). The initial state is used to plan the first action
+in the process. The resulting state of the first action is used as the initial state for the next
+action, and so on. See tutorial on :ref:`planning_process` for more details.
+
+
+Actions
+--------
+
+Action classes are abstractions of the robot's (and, or the operator's) capability to manipulate tools and
+workpieces in the scene. Action classes are used for modeling a process for the following purpose:
+
+* To plan trajectories for robotic motions
+* To simulate and visualize the process in a virtual environment
+* To execute the process on a real robot or a human-robot collaboration process
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    Action
+    RoboticAction
+    LinearMotion
+    FreeMotion
+    OpenGripper
+    CloseGripper
+    ManualWorkpieceMotion
+    HideWorkpieces
+    ShowWorkpieces
+
+States
+------
+
+State classes are used to model the immutable, static state of objects in the planning scene. These include:
+:class:`RobotState` for :class:`compas_fab.robots.Robot`,
+:class:`ToolState` for :class:`compas_fab.robots.Tool` and
+:class:`WorkpieceState` for :class:`compas_fab.robots.Workpiece`.
+The :class:`SceneState` class is a container that holds the state of all objects in the scene.
+
+Typically a robotic process will have an initial (starting) state that is defined manually.
+If sequential planning is used, the initial state is used to plan the first action in the process.
+The resulting state of the first action is used as the initial state for the next action, and so on.
+If non-sequential planning is used, the starting state of actions are inferred from the list of
+actions in the process. See tutorial on :ref:`planning_process` for more details.
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    SceneState
+    WorkpieceState
+    ToolState
+    RobotState
+
+
+"""
+
+from .action import (
+    Action,
+    RoboticAction,
+    LinearMotion,
+    FreeMotion,
+    OpenGripper,
+    CloseGripper,
+    ManualWorkpieceMotion,
+    HideWorkpieces,
+    ShowWorkpieces,
+)
+
+from .state import (
+    SceneState,
+    WorkpieceState,
+    ToolState,
+    RobotState,
+)
+
+__all__ = [
+    "Action",
+    "RoboticAction",
+    "LinearMotion",
+    "FreeMotion",
+    "OpenGripper",
+    "CloseGripper",
+    "ManualWorkpieceMotion",
+    "HideWorkpieces",
+    "ShowWorkpieces",
+    "SceneState",
+    "WorkpieceState",
+    "ToolState",
+    "RobotState",
+]