C++ guide and API reference#
All declarations live in the isaacsim::foundation::objects namespace.
#include <isaacsim/foundation/objects/Stage.hpp>
#include <isaacsim/foundation/objects/Prim.hpp>
// shapes, lights, camera follow the same pattern
using namespace isaacsim::foundation::objects;
Stage#
Stage wraps a USD-compatible stage identified by a numeric ID. The constructor
requires a backend string — either "openusd" or "ovstage" — and
an optional numeric stage ID to attach to an existing stage. Call
openStage or createStage to associate it with a file, then
saveStage / closeStage to complete the lifecycle:
Stage stage("openusd");
stage.createStage(); // blank stage
stage.definePrim("/World", "Xform");
stage.addReference("/path/to/robot.usd", "/World/Robot");
stage.saveStage("/tmp/scene.usda");
stage.closeStage();
Use isValid() to guard against an uninitialized or closed stage:
if (!stage.isValid())
stage.openStage("/assets/scene.usda");
exportStageToString / importStageFromString round-trip the root layer
as a USDA string without touching the filesystem:
std::string usda = stage.exportStageToString();
Stage copy("openusd");
copy.importStageFromString(usda);
generateStringRepresentation returns a human-readable summary of the
stage hierarchy ("tree" or "list" mode):
std::cout << stage.generateStringRepresentation("tree");
Stage metadata (up-axis, units, time codes) can be read and written at any time:
stage.setUpAxis("Z");
stage.setUnits(/*metersPerUnit=*/0.01f, /*kilogramsPerUnit=*/1.0f);
auto [metersPerUnit, kilogramsPerUnit] = stage.getUnits();
auto [start, end, fps] = stage.getTimeCode();
Prim#
Prim wraps one or more USD prim paths and provides batch operations for
attributes, schemas, and variant selections. Pass a single path string or a
std::vector<std::string>; regular expressions are expanded against the
active stage unless resolvePaths is false:
Prim cube("/World/Cube");
Prim robots({ "/World/Robot0", "/World/Robot1" });
// Query type and hierarchy
auto names = cube.getName(); // { "Cube" }
auto parents = robots.getParent(); // { "/World", "/World" }
// Read and write a custom attribute across all wrapped prims
robots.createAttribute("mass", "float");
robots.setAttributeValues("mass", array::Array{ 10.0f, 12.5f });
// Apply a USD API schema
cube.applyApi("PhysicsRigidBodyAPI");
Variant selections can be queried and changed in one call:
auto sel = robots.getVariantSelection(); // { {set -> variant}, ... }
robots.setVariantSelection({ {"lod", "high"} });
Xform#
Xform extends Prim with pose (position/orientation) and scale
management in both world and local frames, visibility control, and a
default-state mechanism for resetting prims to a previously recorded pose.
Transform operations on non-root articulation links are not supported.
Include: <isaacsim/foundation/objects/Xform.hpp>
Camera#
Camera extends Xform and wraps one or more UsdGeomCamera prims.
It exposes batch get/set methods for focal length, focus distance, aperture,
f-stop, projection type, clipping range, shutter timing, and stereo role.
Include: <isaacsim/foundation/objects/Camera.hpp>
Mesh#
Mesh extends Xform and wraps one or more UsdGeomMesh prims. It
exposes batch get/set methods for points, normals, display colors, and face,
crease, corner, and subdivision specifications. Mesh attributes are ragged, so
these methods take and return one array per prim rather than a single batched
array. When creating prims, it can generate the geometry of a set of built-in
primitives (Cone, Cube, Cylinder, Disk, Plane, Sphere,
Torus).
Include: <isaacsim/foundation/objects/Mesh.hpp>
Shapes#
Shape is the abstract base class that extends Xform with display
color control and a updateExtents interface. Concrete subclasses
(Capsule, Cone, Cube, Cylinder, Plane, Sphere) author
the corresponding UsdGeom prim and keep USD extents synchronized with their
geometry attributes.
Include: <isaacsim/foundation/objects/shapes/<ClassName>.hpp>
Lights#
Light is the abstract base class that extends Xform with intensity,
color, exposure, and shadow controls. Concrete subclasses (CylinderLight,
DiskLight, DistantLight, DomeLight, RectLight, SphereLight)
wrap the corresponding UsdLux prim type.
Include: <isaacsim/foundation/objects/lights/<ClassName>.hpp>
Physics scenes#
PhysicsScene extends Prim. It wraps one or more UsdPhysicsScene prims,
applies the NewtonSceneAPI schema to each of them, and exposes gravity plus the
solver-agnostic settings.
physics_scenes::PhysicsScene scene("/World/physicsScene");
// gravity is given as a vector in stage units per second squared
scene.setGravities(array::Array(std::vector<float>{ 0.0f, 0.0f, -9.81f }));
scene.setDeltaTimes(array::Array( 1.0f / 120.0f ));
getGravities resolves the two sentinels USD defines for these attributes: a zero
physics:gravityDirection means the stage’s down axis, and a negative
physics:gravityMagnitude (including its -inf default) means the standard gravity
of 9.81 m/s² expressed in stage units. Authored magnitudes are taken as-is, since the
schema documents them in distance/second/second.
The solver-specific subclasses apply their own API schema on top and declare their own
setDeltaTimes / getDeltaTimes. setDeltaTimes writes the solver’s own attribute and calls the base
implementation, so the solver-agnostic delta time stays in sync; getDeltaTimes reports the
solver’s own attribute, falling back to the base one when the solver schema is not applied.
These methods are not virtual, so the one that runs is chosen by the static type of the
handle:
physics_scenes::PhysxScene physx("/World/physicsScene");
physx.setSolverTypes("TGS");
physics_scenes::PhysxGpuConfiguration configuration; // unset fields are left untouched
configuration.gpuMaximumPartitionCount = array::Array(std::vector<int32_t>{ 16 });
physx.setGpuConfiguration(configuration);
physics_scenes::NewtonMjcScene mjc("/World/mjcScene");
mjc.setIntegrators("implicitfast");
NewtonMjcScene requires the MuJoCo USD schemas to be registered in the running
process; its constructor throws otherwise.
Include: <isaacsim/foundation/objects/physics_scenes/<ClassName>.hpp>
API reference#
Fully qualified namespace: isaacsim::foundation::objects
-
namespace objects#
Classes Summary#
- Camera
High-level wrapper over one or more USD Camera prims.
- Mesh
Wrapper over one or more USD Mesh (points connected into edges and faces) prims.
- Prim
High-level wrapper over one or more USD prims for batch attribute and schema operations.
- Stage
Wrapper around a USD stage providing lifecycle and scene-level operations.
- Xform
High-level wrapper over one or more USD Xform prims for transform and visibility operations.
Namespaces Summary#
Typedefs Summary#
- ColorType
Variant type for display colors: a single color token, a list of color tokens, or a numeric RGB array.
- InputValueType
- OutputValueType