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

C++ with Python Hello World

Introduces the minimal native extension and Python binding interface.

C++ with Python JSON Pipeline

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.