Port "model directives" scene assembly DSL

[ggould-tri]

This is a generalization of #10022 and largely subsumes that work.

Following #10022, TRI developed an internal yaml-based language for assembling a collection of SDF/URDF-specified entities into a scene. This was necessary to manage the potentially dozens of sdfs contributing to each of our simulations. The language supports named frames, adding sdfs at particular offsets from those frames, and arbitrary recursive inclusion. The scenario assembly layer also has hooks for injecting modeling error (which brings weld joints into the reach of stochastic scenarios #13251).

Porting this language to Drake would be (we hope) a temporary accommodation for SDF's lack of composability or an inclusion mechanism, allowing data-oriented specification of complex scenes rather than needing to do it all in python or C++. However we hope that eventually improvements in SDF would remove the need for this mechanism.

[EricCousineau-TRI]

FTR One thing that model directives lack (in their current edition in Anzu) is a sense of "encapsulation". For example, a model directive for a gripper can depend on a frame defined outside that model directive, making the directive invalid as a standalone (which really sucks for things like testing, etc.), and requires you to know the magical interface the directives expect.

I've tried to address that in the (current draft) proposal for Model Composition in SDFormat: http://sdformat.org/tutorials?tut=composition_proposal&#1-1-standalone-components-individual-files (permalink)

Relates https://github.com/osrf/sdformat/issues/278

That all being said, the current SDFormat proposal may not be optimal (e.g. it may introduce too many layers of nesting, etc.)

[ggould-tri]

Strong agree -- the lack of encapsulation is a nasty landmine in the current model directives. And of course since SDF is still the presumptive long-term solution we should relentlessly steal its proposed formal semantics where applicable.

[ggould-tri]

FYI, a design discussion within Anzu yielded this design result there, which I scribe here for reference and fair warning that this design is likely coming for drake.

Notes from vcon with @grant-gould @eric-cousineau @ian-mcmahon @jeremy-nimmer

The proposal is:

• All file names in anzu model directives will be replaced with URIs.
• Model directive parsing will resolve URIs by replacing the text package://foo/ with the result of PackageMap.GetPath(foo) on some package_map. There will be no resolution of other URI schemes (eg model:) in model directives (the sdf/urdf parsers may and do provide such resolution; that's on them).
• The PackageMap used for model directive resolution will be based on either a default-constructed PackageMap or one passed in or extracted from a passed-in parser.
  • That PackageMap will be augmented within ProcessModelDirectives with an additional package: "drake" will resolve to the result of drake::MaybeGetDrakePath()
  • That PackageMap will be augmented in a (non-bashmu'able) wrapper around ProcessModelDirectives with an additional package: "anzu" will resolve to the top level of the anzu runfiles (via a new anzu analogy to drake::MaybeGetDrakePath())
• This augmented PackageMap will also be the one used in parsing, so that the sdf and urdf parsers can use whatever the drake and anzu virtual packages in whatever resolution conventions spark their joy.
• These changes having been made, we expect that the add_package_path directive will no longer be necessary and can be removed.

Additionally:

• Someone who better understands the complexities of the problem (@eric-cousineau ?) will file drake issue(s) for
  • replacing or wrapping PackageMap with a more generic resolution functor and for
  • rationalizing drake's many package.xml files into a more reasonable topology.

[ggould-tri]

FYI @sammy-tri has requested that this migration to drake not proceed until he has finished some related work on the upstream feature (reference anzu #⁠4963). Talk to Sammy or me for details if this is blocking you.

[ggould-tri]

FYI the code in question contains a workaround for #13624, which I am mentioning here so that github puts appropriate notifying badges on the issues.

[ggould-tri]

Recording an items from downstream:

• 10531 would augment and simplify this feature.

  • Currently model directives contains a mechanism ("add_package_path") to import packages.
  • In fact this mechanism is a design defect, as only the caller can know how to resolve a given package (because this involves figuring out how the relevant workspace, installation, or bazel external should handle resource resolution).
  • We would prefer to remove the mechanism, but this would be much simpler if there were exactly one drake package.

[ggould-tri]

https://github.com/ggould-tri/drake/pull/new/model_directives_undev moves model directives out of dev and brings all tests to passing. Still needed:

• [x] Forward-port any changes from the anzu side eg anzu#5340
• [x] Update README to reflect those changes eg base frame is required in AddFrame transforms.
• ~[ ] Wire into Parser so it can be triggered from python~ -- This doesn't work and is a arguably a layering violation anyway.