Skip to content

Commit

Permalink
Merge pull request #14038 from ggould-tri/model_directives_undev
Browse files Browse the repository at this point in the history
"Model directives" scene assembly DSL
  • Loading branch information
sammy-tri authored Sep 29, 2020
2 parents aef3590 + d1eb95b commit ae06238
Show file tree
Hide file tree
Showing 20 changed files with 473 additions and 476 deletions.
64 changes: 64 additions & 0 deletions multibody/parsing/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,11 @@ drake_cc_package_library(
":detail_scene_graph",
":detail_sdf_parser",
":detail_urdf_parser",
":model_directives",
":package_map",
":parser",
":process_model_directives",
":scoped_names",
],
)

Expand Down Expand Up @@ -166,6 +169,43 @@ drake_cc_library(
],
)

drake_cc_library(
name = "model_directives",
hdrs = [
"model_directives.h",
],
deps = [
"//common:essential",
"//common:name_value",
"//common/schema:transform",
"//math:geometric_transform",
],
)

drake_cc_library(
name = "process_model_directives",
srcs = ["process_model_directives.cc"],
hdrs = ["process_model_directives.h"],
deps = [
":model_directives",
":parser",
":scoped_names",
"//common:filesystem",
"//common:find_resource",
"//common/yaml:yaml_read_archive",
"//multibody/plant",
],
)

drake_cc_library(
name = "scoped_names",
srcs = ["scoped_names.cc"],
hdrs = ["scoped_names.h"],
deps = [
"//multibody/plant",
],
)

drake_cc_library(
name = "test_loaders",
testonly = 1,
Expand Down Expand Up @@ -224,6 +264,30 @@ drake_cc_googletest(
],
)

filegroup(
name = "process_model_directives_test_models",
testonly = True,
data = glob(["test/process_model_directives_test/**"]),
)

drake_cc_googletest(
name = "process_model_directives_test",
data = [
":process_model_directives_test_models",
],
deps = [
":process_model_directives",
],
)

drake_cc_googletest(
name = "model_directives_test",
deps = [
":model_directives",
"//common/yaml:yaml_read_archive",
],
)

drake_cc_googletest(
name = "detail_common_test",
deps = [
Expand Down
103 changes: 103 additions & 0 deletions multibody/parsing/README_model_directives.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
The Model Directives mechanism
==============================

"Model Directives" is a small YAML-based language for building a complex
MultibodyPlant-based scene out of numerous `.sdf` and `.urdf` files. For
instance in the TRI dish-loading demo we have individual SDFormat files for
the counter, sink, cameras, pedestal, arm, gripper, and each manipuland. A
single SDFormat for this would be unwieldy and difficult to maintain and
collaborate on, but SDFormat's file inclusion mechanisms have not yet proven
adequate to this task.

We expect that this mechanism will be temporary and will be removed
[when SDFormat adds similar functionality](#conditions-for-deprecation).
Users should be aware that this library will be deprecated if/when sdformat
reaches feature parity with it.


## Syntax

The easiest syntax reference is the unit test files in
`test/process_model_directives_test/*.yaml` of this directory.

A model directives file is a YAML file with a top level `directives:` group.
Within this group are a series of directives, which are described in detail in
`model_directives.h`. These directives can add model instances and add frames
to them and welds between them.


## Use

The easiest use reference is the unit test `process_model_directives_test.cc`.

A simple example of a use would be:

```cpp
ModelDirectives station_directives = LoadModelDirectives(
FindResourceOrThrow("my_exciting_project/models/my_scene.yaml"));
MultibodyPlant<double> plant;
ProcessModelDirectives(station_directives, &plant);
plant.Finalize();
```
Or, if you are connecting a scene graph:
```cpp
DiagramBuilder builder;
ModelDirectives station_directives = LoadModelDirectives(
FindResourceOrThrow("my_exciting_project/models/my_scene.yaml"));
auto [plant, scene_graph] =
AddMultibodyPlantSceneGraph<double>(&builder, 0.0);;
ProcessModelDirectives(station_directives, &plant);
plant.Finalize();
```

This loads the model directives from that filename, constructs a plant, and
uses the model directives to populate the plant.


## Scoping

Elements (frames, bodies, etc.) in `MultibodyPlant` belong to model instances.
To acknowledge this, and support "faux" composition, we introduce scoping via
names.

Names can be scoped implicitly or explicitly, and this scoping supports
multiple levels of "nesting" -- insofar as model instances in MultibodyPlant
can denote hierarchy (see #14043 for more info).

Names are delimited by `::`; the last name portion indicates the element name,
and all preceding portions indicate the model instance name. For this reason,
element names themselves should not contain `::`.

(The `::` convention is used for consistency with the emerging namespace
syntax for SDFormat, soon to be required in SDFormat 1.8.)

Thus:

- `my_frame`: No explicit model instance, the frame is `my_frame`.
- `my_model::my_frame`: The model instance is `my_model`, the frame is
`my_frame`.
- `top_level::my_model::my_frame`: The model instance is
`top_level::my_model`, the frame is `my_frame`.


## Conditions for deprecation

We expect and hope to deprecate this mechanism when either:

SDFormat properly specifies, and Drake supports, the following:

* What `<include/>` statements should *really* do (e.g. namespacing models,
joints, etc.) without kludging Drake's parsing
* See <http://sdformat.org/tutorials?tut=composition_proposal&cat=pose_semantics_docs&> for the progress of the proposed formal semantics.
* How to weld models together with joints external to the models


OR if we find a mechanism whereby xacro could accomplish the same thing:

* Drake's `package://` / `model://` mechanism were mature and correct, and
`sdformat` didn't use singletons for search paths.
* It was easier for one xacro to locate other xacros (possibly via a
workaround using a wrapper script to inject the appropriate drake source
or resource path)
64 changes: 0 additions & 64 deletions multibody/parsing/dev/BUILD.bazel

This file was deleted.

89 changes: 0 additions & 89 deletions multibody/parsing/dev/README.md

This file was deleted.

Loading

0 comments on commit ae06238

Please sign in to comment.