MuJoCo Include

[vikashplus]

MuJoCo "include" for composing models is a very powerful feature. It is very useful when one has a large library of models and wants composability between them. Further developing this functionality to support more features can be generally quite useful. There is a small update that time and again I have felt the need for -- a way to control relative file paths

MuJoCo currently supports specifying file location as a relative path to the directory of the main MJCF file. This works well where there is a single level of nesting. (e.g SceneFile includes ArmFile, ArmFile includes GripperFile). This breaks down quite quickly if there are multiple levels of includes (e.g. SceneFile includes ArmFile which includes GripperFiles). The primary reason is difficulty in resolving relative paths. (GripperFiles works for Arm base dir, but not necessarily for Scene base dir)

My proposal is to add another attribute to allow users to control the relative paths.

1. <include name="scene.xml" resolve_relative="base" /> default resolution is wrt to main MJCF file resulting in scene\arm and scene\gripper as resolved path
2. <include name="scene.xml" resolve_relative="file"/> resolve path wrt to the file that is calling the include, resulting in scene\arm and scene\arm\gripper as the resolved path.
3. <include name="scene.xml" resolve_relative="root"/> use absolute path, resulting in ~\...\arm and ~\...\gripper as the resolved path.

[vikashplus]

The more I work with includes, the more I'm convinced that it's one of the most under-appreciated features of MuJoCo.

As a data point, RoboHive is seamlessly using over 500 include-statements to share various assets across different scenes of varying complexity. This greatly simplifies the overall framework preventing us (a) from copying models (b) seemingly pushing model updates (c) preventing the repo size from blowing up.

I have debated its importance with @erez-tom and @yuvaltassa for a long time. Given its potential, I'll strongly advocate for it :)

Feature 1: Allow users to specify path resolution options.

• See the previous post in this thread

Feature 2: Allow users to include a chain multiple times to allow making copies of robots

• This will likely require resolving naming conflicts.
• NameSpacing by prepending names(copyID) can be a naive fix

Feature 3: Allow users to include and attach a tree to a parent note within another subtree.

• This is massively useful for composing models (multiple arms on a body, grippers on arms, etc.)
• Complication is on how to resolve global conflicts
  • My proposal will be to leverage childclass. Let's consider two models A and B with bodies a1..an, and b1...bn. While including A inside B with b3 as the parent, A will be introduced with the tag childclass="A_defaults" as the child of b3. Where "A_defaults" is the global default for A. This should recursively handle all default overrides (I think)
  • For non-kinematic-chain-specific tags (options, visuals etc.), we can continue with the current override convention.
• Another complication is -- how to resolve the ordering of things like tendons and actuators.
  • My vote will be on harmonizing the chain injection and its dependency injection i.e. tendons, actuators, etc. of A should get injected just after the parent i.e. b3

I'm sure there are lots of corner cases. I'm hoping that we can use this thread to evolve this discussion.

[vmstavens]

All of these sound amazing! Any news on any progress regarding these features?

[yuvaltassa]

Yes. @kbayes can give an update, I believe the core of what @vikashplus is asking for should come out soon.

[vmstavens]

Yes. @kbayes can give an update, I believe the core of what @vikashplus is asking for should come out soon.

Awesome! Thank you so much for the quick response. Looking forward to integrating these new features into my MuJoCo setup!

[kbayes]

Include is fixed in terms of asset file paths are resolved relative to the directory of the included file and not the base file. This also works for nested included files as well.

[vmstavens]

That is great, how is the progress with Feature 2 and Feature 3 @kbayes?

[jonzamora]

+1 to this! @kbayes is there an update on these features?

[kbayes]

Hi @jonzamora, replicate will be available in the next MuJoCo release. I believe this might be mostly a good solution to Feature 2. The attach feature of Feature 3, is currently being worked on. This feature is complicated and requires some overhaul of the compiler code.

[jonzamora]

Sounds great, thanks for the update and timely response! @kbayes