MotionBuilder

class bapsf_motion.motion_builder.core.MotionBuilder(space: str | List[Dict[str, Any]], layers: List[Dict[str, Any]] | None = None, exclusions: List[Dict[str, Any]] | None = None, layer_to_motionlist_scheme: str = 'sequential')

Bases: MBItem

A class that manages all the functionality around probe drive motion in the motion space. This functionality includes:

Defining the motion space the probe moves in.
Generating the motion list for a motion sequence.
Generating motion trajectories to avoid obstacles in the motion space.

Parameters:

space
layers
exclusions
layer_to_motionlist_scheme (str) – ('sequential' or 'merge') The style in which the point layers are combined to form the motion list. 'sequential' means that the point layers are added sequentially to form the motion list, and 'merge' means the point layers are merged together (i.e. removing duplicate points and sorting points) to form one “global” motion list. (DEFAULT 'sequential')

Attributes Summary

`base_name`	Base name for associated items in the `Dataset`.
`base_names`	Dictionary of motion builder item base names.
`config`	Dictionary containing the full configuration of the motion builder.
`exclusions`	List of added exclusion layers.
`item`	The representative motion builder item in the `Dataset`.
`layer_to_motionlist_scheme`	The style in which the point layers are combined to form the motion list.
`layers`	List of added point "motion list" layers.
`mask`	A \(N\)-D `DataArray` representing a boolean mask of the motion space.
`mask_name`	Name of the `mask` item it the `Dataset`.
`mask_resolution`	Tuple containing the spatial resolution of each dimension of the motion space (i.e. grid spacing in each dimension).
`motion_list`	Return the current motion list.
`mspace_coords`	Dictionary-like container of motion space coordinates.
`mspace_dims`	Tuple of motion space dimension names.
`mspace_ndims`	Dimensionality of the motion space.
`name`	Name of the motion builder item in the `Dataset`.
`name_pattern`	The naming pattern for motion builder items in the `Dataset`.

Methods Summary

`add_exclusion`(ex_type, **settings)	Add an exclusion "layer" to the motion builder.
`add_layer`(ly_type, **settings)	Add a "point" layer to the motion builder.
`clear_motion_list`()	Clear/delete the currently constructed motion list.
`drop_vars`(names, *[, errors])	Drop variables from this dataset.
`flatten_points`(points)	Take a \(M \times \cdots \times N \times S\) array `points` and flatten it into a \(Q \times S\) array where \(Q\) is the product of \(M \times \cdots \times N\).
`generate`()	Generated the motion list from the currently defined motion space, motion layers, and motion exclusions in the `Dataset`.
`generate_excluded_mask`(points)	Generate a boolean mask for the given set of `points` where `True` indicates the point is valid and `False` the point is in an excluded region.
`get_insertion_point`()	Get the insertion point associated with the `GovernExclusion`.
`is_excluded`(point)	Check if `point` resides in an excluded region of the motion space or not.
`plot_mask`()
`rebuild_mask`()	Rebuild the current `mask` from the currently defined motion space and exclusion layers.
`remove_exclusion`(name)	Completely remove an exclusion "layer" from the motion builder.
`remove_layer`(name)	Completely remove a layer from the motion builder.

Attributes Documentation

base_name: Base name for associated items in the Dataset.

base_names = {'exclusion': <property object>, 'layer': <property object>}: Dictionary of motion builder item base names.

config: Dictionary containing the full configuration of the motion builder.

exclusions: List of added exclusion layers.

item: The representative motion builder item in the Dataset.

layer_to_motionlist_scheme: The style in which the point layers are combined to form the motion list. 'sequential' means that the point layers are added sequentially to form the motion list, and 'merge' means the point layers are merged together (i.e. remove duplicate points and sort points) to form one “global” motion list.

layers: List of added point “motion list” layers.

mask: A \(N\)-D DataArray representing a boolean mask of the motion space. The mask is True where a probe drive is allowed to move, and False otherwise.

mask_name: Name of the mask item it the Dataset.

mask_resolution: Tuple containing the spatial resolution of each dimension of the motion space (i.e. grid spacing in each dimension).

motion_list: Return the current motion list. If the motion list has not been generated, then it will be done automatically. The returned DataArray will have a dimensionality of \(M \times N\) when \(M\) is the number of points to move the probe to and \(N\) is the equal to the motion space dimensionality mspace_ndims.

mspace_coords: Dictionary-like container of motion space coordinates. Keys are given by mspace_dims. Quick access to coords of mask.

mspace_dims: Tuple of motion space dimension names. Quick access to dims of mask.

mspace_ndims: Dimensionality of the motion space. Synonymous with the number of axes of the probe drive.

name: Name of the motion builder item in the Dataset.

name_pattern: The naming pattern for motion builder items in the Dataset.

Methods Documentation

add_exclusion(ex_type: str, **settings)

Add an exclusion “layer” to the motion builder.

Parameters:

ex_type (str) – String naming the type of exclusion to be defined.
settings (Dict[str, Any]) – Dictionary defining the configuration of the exclusion “layer”. Key-value pairs should correspond the input arguments of the class associated with ex_type.

See also

layer_factory

clear_motion_list(): Clear/delete the currently constructed motion list.

drop_vars(names: str, *, errors: Literal['raise', 'ignore'] = 'raise')

Drop variables from this dataset.

Parameters:

names (Hashable or iterable of Hashable or Callable) – Name(s) of variables to drop. If a Callable, this object is passed as its only argument and its result is used.
errors ({"raise", "ignore"}, default: "raise") – If ‘raise’, raises a ValueError error if any of the variable passed are not in the dataset. If ‘ignore’, any given names that are in the dataset are dropped and no error is raised.

Examples

>>> dataset = xr.Dataset(
...     {
...         "temperature": (
...             ["time", "latitude", "longitude"],
...             [[[25.5, 26.3], [27.1, 28.0]]],
...         ),
...         "humidity": (
...             ["time", "latitude", "longitude"],
...             [[[65.0, 63.8], [58.2, 59.6]]],
...         ),
...         "wind_speed": (
...             ["time", "latitude", "longitude"],
...             [[[10.2, 8.5], [12.1, 9.8]]],
...         ),
...     },
...     coords={
...         "time": pd.date_range("2023-07-01", periods=1),
...         "latitude": [40.0, 40.2],
...         "longitude": [-75.0, -74.8],
...     },
... )
>>> dataset
<xarray.Dataset> Size: 136B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time         (time) datetime64[us] 8B 2023-07-01
  * latitude     (latitude) float64 16B 40.0 40.2
  * longitude    (longitude) float64 16B -75.0 -74.8
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    humidity     (time, latitude, longitude) float64 32B 65.0 63.8 58.2 59.6
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Drop the ‘humidity’ variable

>>> dataset.drop_vars(["humidity"])
<xarray.Dataset> Size: 104B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time         (time) datetime64[us] 8B 2023-07-01
  * latitude     (latitude) float64 16B 40.0 40.2
  * longitude    (longitude) float64 16B -75.0 -74.8
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Drop the ‘humidity’, ‘temperature’ variables

>>> dataset.drop_vars(["humidity", "temperature"])
<xarray.Dataset> Size: 72B
Dimensions:     (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time        (time) datetime64[us] 8B 2023-07-01
  * latitude    (latitude) float64 16B 40.0 40.2
  * longitude   (longitude) float64 16B -75.0 -74.8
Data variables:
    wind_speed  (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Drop all indexes

>>> dataset.drop_vars(lambda x: x.indexes)
<xarray.Dataset> Size: 96B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Dimensions without coordinates: time, latitude, longitude
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    humidity     (time, latitude, longitude) float64 32B 65.0 63.8 58.2 59.6
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Attempt to drop non-existent variable with errors=”ignore”

>>> dataset.drop_vars(["pressure"], errors="ignore")
<xarray.Dataset> Size: 136B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time         (time) datetime64[us] 8B 2023-07-01
  * latitude     (latitude) float64 16B 40.0 40.2
  * longitude    (longitude) float64 16B -75.0 -74.8
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    humidity     (time, latitude, longitude) float64 32B 65.0 63.8 58.2 59.6
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Attempt to drop non-existent variable with errors=”raise”

>>> dataset.drop_vars(["pressure"], errors="raise")
Traceback (most recent call last):
ValueError: These variables cannot be found in this dataset: ['pressure']

Raises:: ValueError – Raised if you attempt to drop a variable which is not present, and the kwarg errors='raise'.
Returns:: dropped
Return type:: Dataset