chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Introduce explicit VFS in Python MjVfs

Browse Source 
This change introduces MjVFS, an explicit object to mirror the C mjVFS. This is meant to replace the MjSpec.assets dict. This latter while convenient guides users towards harmful authoring patterns with respect to data duplication and spec attachment workflows. Making VFS management explicit should encourage better memory usage and allow us to make better compile time optimizations.

From this change, `spec.assets` is deprecated. However we will temporarily support backwards compatibility due to the wide spread usage. An error will be thrown if calling code tries to use a spec that uses both the assets dict and the new MjVfs.

PiperOrigin-RevId: 908772050
Change-Id: I77c6d0369307fc300c954768fed17401261e18da
This commit is contained in:
Sam Haves
2026-05-01 09:33:43 -07:00
committed by Copybara-Service
parent 910b3336ed
commit 723b8b1ea6
10 changed files with 599 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/mujoco/specs.cc
+102 -7
View File
@@ -18,6 +18,7 @@
#include <cstring>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view> // IWYU pragma: keep
#include <unordered_map>
@@ -33,6 +34,7 @@
#include "specs_wrapper.h" // IWYU pragma: keep
#include "raw.h"
#include "structs.h" // IWYU pragma: keep
#include "vfs.h"
#include <pybind11/cast.h>
#include <pybind11/eigen.h>
#include <pybind11/eigen/matrix.h>
@@ -264,6 +266,49 @@ PYBIND11_MODULE(_specs, m) {
DefineArray<float>(m, "MjFloatVec");
DefineArray<int>(m, "MjIntVec");
// ============================= MJVFS =====================================
py::class_<MjVfs>(m, "MjVfs")
.def(py::init<>())
.def("close", &MjVfs::Close)
.def("__enter__", [](MjVfs& self) -> MjVfs& { return self; })
.def("__exit__",
[](MjVfs& self, py::object, py::object, py::object) {
self.Close();
})
.def("__setitem__",
[](MjVfs& self, const std::string& name, py::bytes data) {
if (!self.is_open()) {
throw std::runtime_error("VFS is closed");
}
std::string_view buffer = data;
const int err = mj_addBufferVFS(
self.get(), name.c_str(), buffer.data(), buffer.size());
if (err == 2) {
throw py::value_error(
"Repeated file name in VFS: " + name);
} else if (err) {
throw py::value_error(
"Failed to add buffer to VFS: " + name);
}
})
.def("__delitem__",
[](MjVfs& self, const std::string& name) {
if (!self.is_open()) {
throw std::runtime_error("VFS is closed");
}
if (mj_deleteFileVFS(self.get(), name.c_str())) {
throw py::key_error(name);
}
})
.def("__contains__",
[](MjVfs& self, const std::string& name) {
if (!self.is_open()) {
throw std::runtime_error("VFS is closed");
}
return mj_containsBufferVFS(self.get(), name.c_str()) == 1;
});
// ============================= MJSPEC =====================================
mjSpec.def(py::init<>());
mjSpec.def_property_readonly(
@@ -272,7 +317,26 @@ PYBIND11_MODULE(_specs, m) {
"from_file",
[](std::string& filename,
std::optional<std::unordered_map<std::string, py::bytes>>& include,
std::optional<py::dict>& assets) -> MjSpec {
std::optional<py::dict>& assets,
MjVfs* vfs) -> MjSpec {
if (vfs && (include.has_value() || assets.has_value())) {
throw py::value_error(
"Cannot specify both 'vfs' and 'include'/'assets'.");
}
if (vfs) {
raw::MjSpec* spec;
{
py::gil_scoped_release no_gil;
char error[1024];
spec = InterceptMjErrors(mj_parse)(
filename.c_str(), nullptr, vfs->get(),
error, sizeof(error));
if (!spec) {
throw py::value_error(error);
}
}
return MjSpec(spec);
}
const auto files = _impl::ConvertAssetsDict(include);
raw::MjSpec* spec;
{
@@ -294,7 +358,8 @@ PYBIND11_MODULE(_specs, m) {
return MjSpec(spec);
},
py::arg("filename"), py::arg("include") = py::none(),
py::arg("assets") = py::none(), R"mydelimiter(
py::arg("assets") = py::none(), py::arg("vfs") = py::none(),
R"mydelimiter(
Creates a spec from an XML file.
Parameters
@@ -307,13 +372,34 @@ PYBIND11_MODULE(_specs, m) {
assets : dict, optional
A dictionary of assets to be used by the spec. The keys are asset names
and the values are asset contents.
vfs : MjVfs, optional
A VFS to use for resolving includes and assets. Cannot be used with
include or assets.
)mydelimiter",
py::return_value_policy::move);
mjSpec.def_static(
"from_string",
[](std::string& xml,
std::optional<std::unordered_map<std::string, py::bytes>>& include,
std::optional<py::dict>& assets) -> MjSpec {
std::optional<py::dict>& assets,
MjVfs* vfs) -> MjSpec {
if (vfs && (include.has_value() || assets.has_value())) {
throw py::value_error(
"Cannot specify both 'vfs' and 'include'/'assets'.");
}
if (vfs) {
raw::MjSpec* spec;
{
py::gil_scoped_release no_gil;
char error[1024];
spec = InterceptMjErrors(mj_parseXMLString)(
xml.c_str(), vfs->get(), error, sizeof(error));
if (!spec) {
throw py::value_error(error);
}
}
return MjSpec(spec);
}
auto files = _impl::ConvertAssetsDict(include);
raw::MjSpec* spec;
{
@@ -345,7 +431,8 @@ PYBIND11_MODULE(_specs, m) {
return MjSpec(spec);
},
py::arg("xml"), py::arg("include") = py::none(),
py::arg("assets") = py::none(), R"mydelimiter(
py::arg("assets") = py::none(), py::arg("vfs") = py::none(),
R"mydelimiter(
Creates a spec from an XML string.
Parameters
@@ -358,6 +445,9 @@ PYBIND11_MODULE(_specs, m) {
assets : dict, optional
A dictionary of assets to be used by the spec. The keys are asset names
and the values are asset contents.
vfs : MjVfs, optional
A VFS to use for resolving includes and assets. Cannot be used with
include or assets.
)mydelimiter",
py::return_value_policy::move);
mjSpec.def("recompile", [mjmodel_mjdata_from_spec_ptr](
@@ -391,9 +481,14 @@ PYBIND11_MODULE(_specs, m) {
return mjs_findDefault(self.ptr, classname.c_str());
},
py::return_value_policy::reference_internal);
mjSpec.def("compile", [mjmodel_from_raw_ptr](MjSpec& self) -> py::object {
return mjmodel_from_raw_ptr(reinterpret_cast<uintptr_t>(self.Compile()));
});
mjSpec.def("compile",
[mjmodel_from_raw_ptr](MjSpec& self,
std::optional<MjVfs*> vfs) -> py::object {
mjVFS* vfs_ptr = vfs.has_value() ? (*vfs)->get() : nullptr;
return mjmodel_from_raw_ptr(
reinterpret_cast<uintptr_t>(self.Compile(vfs_ptr)));
},
py::arg("vfs") = py::none());
mjSpec.def_property(
"assets",
[](MjSpec& self) -> py::dict {