Expose native Isaac Sim code to Python#
Build an example-local CPython extension that calls an Isaac Sim C++ API, then extend the same interface to exchange structured data. Keep native ownership and exception handling in C++ while presenting a small Python API.
Learning objectives#
After completing this tutorial, you can:
Publish a focused C++ operation through a CPython extension module.
Translate native exceptions at the Python boundary.
Exchange structured data without sharing language-specific object implementations.
Prerequisites#
Complete Install and run.
Install a C++ toolchain, Python, and Python development headers.
On Windows, install Visual Studio 2022 and the Windows SDK.
Run the commands in this tutorial from the repository root.
Examples used#
Example |
Role in this tutorial |
|---|---|
Introduces the minimal native extension and Python binding interface. |
|
Adds structured data and an external C++ dependency. |
Each example page lists its source directory, requirements, and runner commands.
Build the extension modules#
Build each example before running its Python entry point. The runner resolves the native SDK, Python development files, and example-specific dependencies:
source/examples/example.sh build hello_world.cpp_python
source/examples/example.sh run hello_world.cpp_python
source/examples/example.sh build json_pipeline.cpp_python
source/examples/example.sh run json_pipeline.cpp_python
.\source\examples\example.bat build hello_world.cpp_python
.\source\examples\example.bat run hello_world.cpp_python
.\source\examples\example.bat build json_pipeline.cpp_python
.\source\examples\example.bat run json_pipeline.cpp_python
The extension modules remain local to their examples. They are implementation
details rather than public isaacsim packages.
Expose one native operation#
The first extension constructs the C++ Logger inside the wrapper function.
It raises a Python RuntimeError for C++ exceptions so no
exception crosses the CPython C boundary:
PyObject* sayHello(PyObject*, PyObject*)
{
try
{
const isaacsim::common::logging::Logger logger("isaacsim.examples.hello_world.cpp_python");
logger.report("Hello World from C++ with Python.");
Py_RETURN_NONE;
}
catch (const std::exception& error)
{
PyErr_SetString(PyExc_RuntimeError, error.what());
return nullptr;
}
catch (...)
{
PyErr_SetString(PyExc_RuntimeError, "The Isaac Sim C++ API reported an unknown error.");
return nullptr;
}
}
The module method table publishes that function as say_hello. The Python
entry point only imports the built module and invokes the exposed operation:
"""Run the C++ with Python Hello World example."""
import _hello_world_cpp
def main() -> None:
"""Call the example-local C++ binding."""
_hello_world_cpp.say_hello()
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
pass
Keep wrapper functions focused on conversion, lifetime management, and error translation. Put the library operation in C++ and the application workflow in Python.
Exchange structured data#
The JSON pipeline builds a document in C++, uses
isaacsim::common::string::toUpper to transform a value, and returns a
new Python string containing the serialized document:
PyObject* buildDocument(PyObject*, PyObject*)
{
try
{
const nlohmann::json document = {
{ "robot", { { "name", isaacsim::common::string::toUpper("carter") }, { "joints", 7 } } },
};
const std::string serialized = document.dump();
return PyUnicode_FromStringAndSize(serialized.data(), static_cast<Py_ssize_t>(serialized.size()));
}
catch (const std::exception& error)
{
PyErr_SetString(PyExc_RuntimeError, error.what());
return nullptr;
}
catch (...)
{
PyErr_SetString(PyExc_RuntimeError, "The JSON pipeline reported an unknown error.");
return nullptr;
}
}
Python owns decoding and selection. The two languages share text instead of exposing either language’s JSON object implementation across the boundary:
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Run the mixed C++ and Python JSON pipeline example."""
import json
import _json_pipeline_cpp
import jsonpointer
def main() -> None:
"""Build JSON in C++ and select its values from Python."""
document = json.loads(_json_pipeline_cpp.build_document())
name = jsonpointer.resolve_pointer(document, "/robot/name")
joints = jsonpointer.resolve_pointer(document, "/robot/joints")
print(f"Robot {name} has {joints} joints.")
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
pass
Verify both boundaries#
Run the example tests:
source/examples/example.sh test hello_world.cpp_python
source/examples/example.sh test json_pipeline.cpp_python
.\source\examples\example.bat test hello_world.cpp_python
.\source\examples\example.bat test json_pipeline.cpp_python
The first test verifies the native logging call. The second verifies that C++ produces a document that Python can decode and query.
Tradeoffs#
Serialized data is easy to inspect and keeps ownership clear, but it adds parsing cost and validates the document shape at runtime. Prefer a narrow typed function for frequent scalar operations and a serialized document when the payload is structured or must remain implementation-neutral.
Keep example-local extensions private to the application. If an interface must become part of a public package, define its stability, ownership, and error contracts before exposing it to downstream users.
Next steps#
Continue with Author, simulate, and visualize a falling cube to apply the Python API to a complete simulation workflow.