A ROS 2 workspace containing a Gazebo Sim plugin for loading OBJ mesh files directly into simulation scenes.
This workspace provides the obj_mesh_loader package, a Gazebo Sim system plugin that enables loading OBJ mesh files into a simulation world through SDF configuration. The plugin supports loading meshes from various sources (file paths, model URIs, Fuel URIs) and allows customization of pose, scale, and materials.
- ROS 2: A ROS 2 distribution (tested with ROS 2 distributions that support Gazebo Sim)
- Gazebo Sim 8: Gazebo Simulator version 8
- Dependencies:
gz-sim8gz-common5gz-math7gz-plugin2sdformat14ament_cmake(build tool)
mesh_ws/
├── obj_mesh_loader/ # Main package: OBJ mesh loader plugin
│ ├── src/ # Plugin source code
│ ├── include/ # Header files
│ ├── examples/ # Example SDF world files
│ └── test/ # Unit tests
├── models/ # Example models (box model included)
│ └── box/ # Sample box model with OBJ mesh
├── build/ # Build artifacts (generated)
├── install/ # Installation directory (generated)
├── log/ # Build logs (generated)
├── build_mesh_loader.sh # Build script
└── run_mesh_loader.sh # Run example script
Using the provided build script:
cd mesh_ws
./build_mesh_loader.shOr using colcon directly:
cd mesh_ws
source /opt/ros/$ROS_DISTRO/setup.bash
colcon build --packages-select obj_mesh_loader
source install/setup.bashUsing the provided run script:
cd mesh_ws
./run_mesh_loader.shOr manually:
source /opt/ros/$ROS_DISTRO/setup.bash
source install/setup.bash
# Set model path
export GZ_SIM_RESOURCE_PATH=$GZ_SIM_RESOURCE_PATH:$(pwd)/models
export GZ_FILE_PATH=$GZ_FILE_PATH:$(pwd)/models
# Run the example
gz sim install/obj_mesh_loader/share/obj_mesh_loader/examples/obj_mesh_loader_world.sdfsource /opt/ros/$ROS_DISTRO/setup.bash
colcon build --packages-select obj_mesh_loader
source install/setup.bash-
Release build (default in build script):
colcon build --packages-select obj_mesh_loader --cmake-args -DCMAKE_BUILD_TYPE=Release
-
Debug build:
colcon build --packages-select obj_mesh_loader --cmake-args -DCMAKE_BUILD_TYPE=Debug
-
Build with tests:
colcon build --packages-select obj_mesh_loader --cmake-args -DBUILD_TESTING=ON
After building, run the tests:
# Using colcon
colcon test --packages-select obj_mesh_loader
colcon test-result --verbose
# Or using ctest directly
cd build/obj_mesh_loader
ctestThe plugin can be added to any SDF world file. Here's a minimal example:
<?xml version="1.0" ?>
<sdf version="1.6">
<world name="default">
<plugin filename="ObjMeshLoader" name="obj_mesh_loader::ObjMeshLoader">
<obj_uri>model://box/meshes/box.obj</obj_uri>
<name>my_mesh</name>
<pose>0 0 1 0 0 0</pose>
<scale>1 1 1</scale>
</plugin>
</world>
</sdf>For detailed usage instructions, plugin parameters, and more examples, see the package README.
The workspace includes a sample box model located at models/box/ with:
- A 1x1x1 meter cube OBJ mesh
- Model configuration files
- SDF model description
Coordinate system: Up = +Z, Right = +X, Back = +Y
When running Gazebo Sim with this plugin, ensure these environment variables are set:
GZ_SIM_SYSTEM_PLUGIN_PATH: Path to the plugin library (automatically set by the run script)GZ_SIM_RESOURCE_PATH: Paths where Gazebo can find models and resourcesGZ_FILE_PATH: Additional paths for file resolution (used by SystemPaths)
The run_mesh_loader.sh script sets these automatically.
If Gazebo Sim cannot find the plugin:
export GZ_SIM_SYSTEM_PLUGIN_PATH=$GZ_SIM_SYSTEM_PLUGIN_PATH:$(pwd)/install/obj_mesh_loader/libIf model:// URIs are not working:
export GZ_SIM_RESOURCE_PATH=$GZ_SIM_RESOURCE_PATH:$(pwd)/models
export GZ_FILE_PATH=$GZ_FILE_PATH:$(pwd)/models- Ensure all dependencies are installed
- Check that ROS 2 environment is sourced:
source /opt/ros/$ROS_DISTRO/setup.bash - Clean and rebuild:
rm -rf build install log && colcon build
Apache License 2.0 - See LICENSE file for details.
For detailed information about the plugin, its parameters, and advanced usage, see:
- obj_mesh_loader/README.md - Package documentation