`bapsf_motion.motion_builder`
=============================

The :term:`motion builder` (i.e. |MotionBuilder|) has three fundamental
roles for in the framework for probe drive motion:

1. It defines the physical :term:`motion space` at probe drive will
   move in.  This includes any excluded regions where a probe drive
   is not allowed to be, for example a region where a target was
   position in the :term:`LaPD` chamber.
2. Building and generating the :term:`motion list` that would be used
   for a data run.
3. Generating motion trajectories to avoid obstacles in the motion
   space.

Note, the :term:`motion builder` does not move the probe drive, it only
defines and calculates where a probe drive is allowed to be in the
:term:`motion space`.

The |MotionBuilder| class hase four fundamental building blocks:

1. The :term:`motion space` which defines the :math:`N`\ -D space the
   :term:`probe` is supposed to move in.  For example, this would be
   the physical space of the :term:`LaPD`.
2. The `~bapsf_motion.motion_builder.MotionBuilder.mask`, which is a high
   resolution boolean array over the :term:`motion space` indicating
   where a probe is allowed or not allowed to move to.
3. The :term:`motion layers` (sometimes also referred to as
   :term:`point layers`), which defines an array of points where the
   probe ought to move to during a data run.  A single
   :term:`motion layer` can be defined or multiple layers can be
   defined to construct more complex :term:`point layers`.  The
   available layers are summarized :ref:`below <available_layers>`.
4. The :term:`motion exclusions` (sometimes also referred to as
   :term:`exclusion layers`), which defines regions in the
   :term:`motion space` where a probe can not be moved to. A single
   :term:`exclusion layer` can be defined or multiple layers can be
   defined to construct more complex :term:`exclusion layers`.  The
   available exclusions are summarized
   :ref:`below <available_exclusions>`.

The |MotionBuilder| manages all these fundamental building blocks within
a `xarray` `~xarray.DataSet`.  The final :term:`motion list` is
generated by |MotionBuilder| by combining all the fundamental building
blocks.

About Point Layers
------------------

.. note::

    Discuss the mechanics of a motion layer class.  How it creates the
    DataArray. What the DataArray looks like.  How it interacts with
    the motion list DataSet.

.. _available_layers:

Available Layers
~~~~~~~~~~~~~~~~

.. automodsumm:: bapsf_motion.motion_builder.layers
    :groups: mlayers

Creating a New Layer Type
~~~~~~~~~~~~~~~~~~~~~~~~~

About Exclusion Layers
----------------------

.. note::

    Discuss the mechanics of an exclusion layer class.  How it creates
    the DataArray.  What the DataArray looks like.  How it interacts
    with the motion list DataSet.

.. _available_exclusions:

Available Exclusions
~~~~~~~~~~~~~~~~~~~~

.. automodsumm:: bapsf_motion.motion_builder.exclusions
    :groups: mexclusions

Creating a New Exclusion Type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

API
---

.. automodapi:: bapsf_motion.motion_builder