# gs-madrona — A Fork of Madrona and Madrona-MJX for Genesis
It started as a fork of [Madrona](https://github.com/shacklettbp/madrona) for the core C++ implementation, created in 2025. Since the fork, substantial modifications have been made to adapt the codebase for [Genesis simulator](https://github.com/Genesis-Embodied-AI/Genesis), including:
- Integrating Python interface based on [Madrona-MJX](https://github.com/shacklettbp/madrona_mjx) and designed for Genesis.
- Adding new features to support the continuous development. For more details, please refer to [Features Added Since Fork](#features-added-since-fork)
- Removing features not used by Genesis. For more details, please refer to [Removed Features](#removed-features)
Due to the extent of these changes, gs-madrona has diverged significantly from its origins. It is now a fully independent project with no intention of maintaining backward compatibility. Our focus is solely on evolving gs-madrona into a robust and efficient batch renderer for Genesis.
## Scope and Objectives
**gs-madrona** aims to provide a general-purpose **high-throughput batch renderer** that supports both rasterization and single-bounce ray-tracing pipelines.
It is a renderer used in Genesis to provide native support of batched processing. With gs-madrona, multiple environments and cameras can be rendered offscreen in parallel, significantly improving performance compared to renderers doing sequential processing.
At present, batch rendering supports only basic materials, lighting, and shadows. However, we aim to expand its capabilities to include more advanced rendering features.
While gs-madrona currently depends on Genesis, we plan to decouple it in the near future to support broader use cases through a more generic interface.
## Features Added Since Fork
- Support for non-square resolutions
- Shadow rendering in the rasterizer pipeline
- Anti-aliasing support for rasterizer output
- Lighting support (rasterizer and ray tracer) using Genesis-defined light sources
- Unified lighting model between rasterizer and ray tracer
- Support for spot lights and directional lights with intensity and shadow-casting flags
- Automatic mipmap generation for all textures
- CUDA kernel caching with dirty-check rebuild
- Fixed vertex normal computation in the ray tracer
- Benchmark scripts comparing Madrona with other batch renderers, including IsaacLab and ManiSkill
## Removed Features
- Legacy depth-only rendering via color buffer
- Batch rendering pipeline based on JAX
## Known Limitations
- Only color and depth outputs are currently supported
- Shadows are only cast from the first light with `castshadow=true`
- When rendering multiple cameras with different resolutions, the first camera’s resolution is used for the entire batch
## Roadmap / Future Plans
**gs-madrona** will continue evolving to support higher-quality rendering and broader functionality. Upcoming features include:
- Batch rendering support for cameras with varying resolutions
- Normal buffer and semantic/instance segmentation output
- Per-camera dynamic FOV control
- Camera-specific near/far plane configuration
- Light color specification
- Dynamic light parameters (position, direction, intensity, color, enable/disable)
- Light attenuation based on distance and angle
- Ambient lighting control (color and intensity)
- PBR material and texture support
- Output rendering results to video files
## Supported Platforms and Environments
**gs-madrona** should be compatible with any Linux distribution and Python>=3.10. However, it has been tested only with Ubuntu 22.04 and Ubuntu 24.04 for Python 3.10 and 3.12. The rendering pipeline also depends on CUDA, so an NVIDIA graphics card with CUDA 12.4+ support is required for running it. There is no plan to support Windows OS and Mac OS at the moment.
## Performance
FPS comparison of rendering [Franka](https://github.com/Genesis-Embodied-AI/Genesis/blob/main/genesis/assets/xml/franka_emika_panda/panda.xml) with gs-madrona rasterizer and raytracer
Resolution: 128x128
<p align="center">
<img src="./scripts/perf_benchmark/example_report/panda_madrona rasterizer_ madrona raytracer_128x128_comparison_table.png" width="600" alt="FPS of gs-madrona rasterizer vs raytracer" align="center"/>
</p>
<p align="center">
<img src="./scripts/perf_benchmark/example_report/panda_madrona rasterizer_ madrona raytracer_128x128_comparison_plot.png" width="600" alt="FPS of gs-madrona rasterizer vs raytracer" align="center"/>
</p>
## Install (Linux Only)
### Pre-requisite
Please first install the latest version of Genesis to date following the [official README instructions](https://github.com/Genesis-Embodied-AI/Genesis#quick-installation).
### Easy install (x86 only)
Pre-compiled binary wheels for Python>=3.10 are available on PyPI. They can be installed using any Python package manager (e.g. `uv` or `pip`):
```sh
pip install gs-madrona
```
### Build from source
Please first install CUDA toolkit (>= 12.4) following the [official instructions](https://developer.nvidia.com/cuda-toolkit-archive).
```sh
git clone --recurse-submodules https://github.com/Genesis-Embodied-AI/gs-madrona.git
cd gs-madrona
pip install --no-build-isolation -Cbuild-dir=build -v -e .
```
Make sure that the version of `torch` installed on your system that has been pre-compiled against a version of CUDA Toolkit that is equal or newer than the one available on your system. Otherwise, gs-madrona will crash at import (segmentation fault). Please follow the [official instructions](https://pytorch.org/get-started/locally/).
### Testing (Optional)
1. Clone Genesis Simulator repository if not already done
```sh
git clone https://github.com/Genesis-Embodied-AI/Genesis.git
```
2. Run the following example script provided with Genesis
```sh
python Genesis/examples/rigid/single_franka_batch_render.py
```
All the generated images will be stored in the current directory under `./image_output`.
2. To use ray tracer, change the `use_rasterizer=False` in `single_franka_batch_render.py`
```
renderer = gs.options.renderers.BatchRenderer(
use_rasterizer=True,
)
```
### Performance Benchmark
For comprehensive performance benchmarking across multiple renderers (Madrona, Omniverse, PyRender, ManiSkill), please refer to the detailed documentation in `scripts/perf_benchmark/README.md`.
The benchmark suite includes:
- Multi-renderer performance testing
- Batch size and resolution scaling tests
- Rasterizer vs raytracer comparisons
- Automated report generation
- Asset preprocessing utilities
Quick start:
```bash
cd scripts/perf_benchmark
python batch_benchmark.py -f benchmark_config_smoke_test.yml
```
## Acknowledgments
The development of gs-madrona is actively supported by [Genesis AI](https://genesis-ai.company/).
Raw data
{
"_id": null,
"home_page": null,
"name": "gs-madrona",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Alexis Duburcq <alexis.duburcq@gmail.com>, Hongyi Yu <hongyi.yu@genesis-ai.company>",
"keywords": "rendering, graphics, 3d, vulkan, visualization, raytracing",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "# gs-madrona \u2014 A Fork of Madrona and Madrona-MJX for Genesis\n\nIt started as a fork of [Madrona](https://github.com/shacklettbp/madrona) for the core C++ implementation, created in 2025. Since the fork, substantial modifications have been made to adapt the codebase for [Genesis simulator](https://github.com/Genesis-Embodied-AI/Genesis), including:\n- Integrating Python interface based on [Madrona-MJX](https://github.com/shacklettbp/madrona_mjx) and designed for Genesis.\n- Adding new features to support the continuous development. For more details, please refer to [Features Added Since Fork](#features-added-since-fork)\n- Removing features not used by Genesis. For more details, please refer to [Removed Features](#removed-features)\n\nDue to the extent of these changes, gs-madrona has diverged significantly from its origins. It is now a fully independent project with no intention of maintaining backward compatibility. Our focus is solely on evolving gs-madrona into a robust and efficient batch renderer for Genesis.\n\n## Scope and Objectives\n**gs-madrona** aims to provide a general-purpose **high-throughput batch renderer** that supports both rasterization and single-bounce ray-tracing pipelines.\n\nIt is a renderer used in Genesis to provide native support of batched processing. With gs-madrona, multiple environments and cameras can be rendered offscreen in parallel, significantly improving performance compared to renderers doing sequential processing.\n\nAt present, batch rendering supports only basic materials, lighting, and shadows. However, we aim to expand its capabilities to include more advanced rendering features.\n\nWhile gs-madrona currently depends on Genesis, we plan to decouple it in the near future to support broader use cases through a more generic interface.\n\n## Features Added Since Fork\n- Support for non-square resolutions\n- Shadow rendering in the rasterizer pipeline\n- Anti-aliasing support for rasterizer output\n- Lighting support (rasterizer and ray tracer) using Genesis-defined light sources\n- Unified lighting model between rasterizer and ray tracer\n- Support for spot lights and directional lights with intensity and shadow-casting flags\n- Automatic mipmap generation for all textures\n- CUDA kernel caching with dirty-check rebuild\n- Fixed vertex normal computation in the ray tracer\n- Benchmark scripts comparing Madrona with other batch renderers, including IsaacLab and ManiSkill\n\n## Removed Features\n- Legacy depth-only rendering via color buffer\n- Batch rendering pipeline based on JAX\n\n## Known Limitations\n- Only color and depth outputs are currently supported\n- Shadows are only cast from the first light with `castshadow=true`\n- When rendering multiple cameras with different resolutions, the first camera\u2019s resolution is used for the entire batch\n\n## Roadmap / Future Plans\n**gs-madrona** will continue evolving to support higher-quality rendering and broader functionality. Upcoming features include:\n- Batch rendering support for cameras with varying resolutions\n- Normal buffer and semantic/instance segmentation output\n- Per-camera dynamic FOV control\n- Camera-specific near/far plane configuration\n- Light color specification\n- Dynamic light parameters (position, direction, intensity, color, enable/disable)\n- Light attenuation based on distance and angle\n- Ambient lighting control (color and intensity)\n- PBR material and texture support\n- Output rendering results to video files\n\n## Supported Platforms and Environments\n**gs-madrona** should be compatible with any Linux distribution and Python>=3.10. However, it has been tested only with Ubuntu 22.04 and Ubuntu 24.04 for Python 3.10 and 3.12. The rendering pipeline also depends on CUDA, so an NVIDIA graphics card with CUDA 12.4+ support is required for running it. There is no plan to support Windows OS and Mac OS at the moment.\n\n## Performance\nFPS comparison of rendering [Franka](https://github.com/Genesis-Embodied-AI/Genesis/blob/main/genesis/assets/xml/franka_emika_panda/panda.xml) with gs-madrona rasterizer and raytracer\n\nResolution: 128x128\n\n<p align=\"center\">\n <img src=\"./scripts/perf_benchmark/example_report/panda_madrona rasterizer_ madrona raytracer_128x128_comparison_table.png\" width=\"600\" alt=\"FPS of gs-madrona rasterizer vs raytracer\" align=\"center\"/>\n</p>\n\n<p align=\"center\">\n <img src=\"./scripts/perf_benchmark/example_report/panda_madrona rasterizer_ madrona raytracer_128x128_comparison_plot.png\" width=\"600\" alt=\"FPS of gs-madrona rasterizer vs raytracer\" align=\"center\"/>\n</p>\n\n## Install (Linux Only)\n\n### Pre-requisite\nPlease first install the latest version of Genesis to date following the [official README instructions](https://github.com/Genesis-Embodied-AI/Genesis#quick-installation).\n\n### Easy install (x86 only)\nPre-compiled binary wheels for Python>=3.10 are available on PyPI. They can be installed using any Python package manager (e.g. `uv` or `pip`):\n```sh\npip install gs-madrona\n```\n\n### Build from source\nPlease first install CUDA toolkit (>= 12.4) following the [official instructions](https://developer.nvidia.com/cuda-toolkit-archive).\n```sh\ngit clone --recurse-submodules https://github.com/Genesis-Embodied-AI/gs-madrona.git\ncd gs-madrona\npip install --no-build-isolation -Cbuild-dir=build -v -e .\n```\n\nMake sure that the version of `torch` installed on your system that has been pre-compiled against a version of CUDA Toolkit that is equal or newer than the one available on your system. Otherwise, gs-madrona will crash at import (segmentation fault). Please follow the [official instructions](https://pytorch.org/get-started/locally/).\n\n### Testing (Optional)\n1. Clone Genesis Simulator repository if not already done\n```sh\ngit clone https://github.com/Genesis-Embodied-AI/Genesis.git\n```\n\n2. Run the following example script provided with Genesis\n```sh\npython Genesis/examples/rigid/single_franka_batch_render.py\n```\n\nAll the generated images will be stored in the current directory under `./image_output`.\n\n2. To use ray tracer, change the `use_rasterizer=False` in `single_franka_batch_render.py`\n```\nrenderer = gs.options.renderers.BatchRenderer(\n use_rasterizer=True,\n)\n```\n\n### Performance Benchmark\nFor comprehensive performance benchmarking across multiple renderers (Madrona, Omniverse, PyRender, ManiSkill), please refer to the detailed documentation in `scripts/perf_benchmark/README.md`.\n\nThe benchmark suite includes:\n- Multi-renderer performance testing\n- Batch size and resolution scaling tests\n- Rasterizer vs raytracer comparisons\n- Automated report generation\n- Asset preprocessing utilities\n\nQuick start:\n```bash\ncd scripts/perf_benchmark\npython batch_benchmark.py -f benchmark_config_smoke_test.yml\n```\n\n## Acknowledgments\n\nThe development of gs-madrona is actively supported by [Genesis AI](https://genesis-ai.company/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fork from the official Madrona. The fork will be used for Genesis's own Madrona integration.",
"version": "0.0.3",
"project_urls": {
"Repository": "https://github.com/Genesis-Embodied-AI/gs-madrona"
},
"split_keywords": [
"rendering",
" graphics",
" 3d",
" vulkan",
" visualization",
" raytracing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6155896e05ef20d3c1c3ba36f576c110dcfd155fb4d298511738fe8cf3b3c8d1",
"md5": "10dd1ffd18cae1fd34682e42ad0661fe",
"sha256": "fc07c4524a56555ebe62227f9427e40e0775ff66f02a218fc83b973ddef22645"
},
"downloads": -1,
"filename": "gs_madrona-0.0.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "10dd1ffd18cae1fd34682e42ad0661fe",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 63885702,
"upload_time": "2025-08-06T04:12:54",
"upload_time_iso_8601": "2025-08-06T04:12:54.302758Z",
"url": "https://files.pythonhosted.org/packages/61/55/896e05ef20d3c1c3ba36f576c110dcfd155fb4d298511738fe8cf3b3c8d1/gs_madrona-0.0.3-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "576dc36a39ee9f1937b2faff09efe987076ea8ccc94231bbd37efd81858d8891",
"md5": "791951ba5dee258aeb90f611ae0e38c4",
"sha256": "e6022fb07694162038d89f40807c22e7e9cc7f01504a6bde6952f249ed7284d5"
},
"downloads": -1,
"filename": "gs_madrona-0.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "791951ba5dee258aeb90f611ae0e38c4",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 63885615,
"upload_time": "2025-08-06T04:12:59",
"upload_time_iso_8601": "2025-08-06T04:12:59.360381Z",
"url": "https://files.pythonhosted.org/packages/57/6d/c36a39ee9f1937b2faff09efe987076ea8ccc94231bbd37efd81858d8891/gs_madrona-0.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "796e19c5b9154eb87e7751c732ac149d6900290bf3a38a9162fd284048e4e540",
"md5": "b8a131bfcfbb79c0f7950918fed76e86",
"sha256": "eff9b833ea1b459345ef42aaea30b4d76cbc1e67c238ea630f699f4896b7e834"
},
"downloads": -1,
"filename": "gs_madrona-0.0.3-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "b8a131bfcfbb79c0f7950918fed76e86",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 63883049,
"upload_time": "2025-08-06T04:13:04",
"upload_time_iso_8601": "2025-08-06T04:13:04.388209Z",
"url": "https://files.pythonhosted.org/packages/79/6e/19c5b9154eb87e7751c732ac149d6900290bf3a38a9162fd284048e4e540/gs_madrona-0.0.3-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 04:12:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Genesis-Embodied-AI",
"github_project": "gs-madrona",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gs-madrona"
}
JSON
