Geometric primitives

OpenUSD supports various basic geometric primitives, known collectively as UsdGeomGprims, which are considered more performant for both rendering & simulation.

While generally trivial to author, it is important to remember to compute correct extents when deviating from the schema fallback values & to check that the prim target location is writeable. The utility functions in this module expose the usual schema parameters of each Gprim, and perform these extra checks.

The set of available Gprims may not directly match the requirements of other data sources. In some cases, it is possible to “shape” a Gprim to match the input data. For example:

• A rectangular prism can be authored using usdex::core::defineCube followed by usdex::core::setLocalTransform with a non-uniform scale.

• An ellipsoid approximation can be authored using usdex::core::defineSphere and usdex::core::setLocalTransform with a non-uniform scale.

• Several Gprims provide an axis attribute to orient along X, Y, or Z independantly of any XformOps.

Note

If the source data cannot be trivially shaped using these mechanisms, it may be necessary to tesselate the input data model and author a mesh using usdex::core::definePolyMesh.

Functions

pxr::UsdGeomCapsule usdex::core::defineCapsule(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a capsule primitive.

pxr::UsdGeomCapsule usdex::core::defineCapsule(pxr::UsdPrim parent, const std::string &name, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a capsule primitive as a child of the parent prim.

pxr::UsdGeomCapsule usdex::core::defineCapsule(pxr::UsdPrim prim, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a capsule primitive from an existing prim.

pxr::UsdGeomCone usdex::core::defineCone(pxr::UsdPrim parent, const std::string &name, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cone primitive as a child of the parent prim.

pxr::UsdGeomCone usdex::core::defineCone(pxr::UsdPrim prim, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cone primitive from an existing prim.

pxr::UsdGeomCone usdex::core::defineCone(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cone primitive.

pxr::UsdGeomCube usdex::core::defineCube(pxr::UsdPrim prim, const double size=2.0, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cube primitive from an existing prim.

pxr::UsdGeomCube usdex::core::defineCube(pxr::UsdPrim parent, const std::string &name, const double size=2.0, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cube primitive as a child of the parent prim.

pxr::UsdGeomCube usdex::core::defineCube(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const double size=2.0, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cube primitive.

pxr::UsdGeomCylinder usdex::core::defineCylinder(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cylinder primitive.

pxr::UsdGeomCylinder usdex::core::defineCylinder(pxr::UsdPrim prim, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cylinder primitive from an existing prim.

pxr::UsdGeomCylinder usdex::core::defineCylinder(pxr::UsdPrim parent, const std::string &name, const double radius=1.0, const double height=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a cylinder primitive as a child of the parent prim.

pxr::UsdGeomPlane usdex::core::definePlane(pxr::UsdPrim prim, const double width=2.0, const double length=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a plane primitive from an existing prim.

pxr::UsdGeomPlane usdex::core::definePlane(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const double width=2.0, const double length=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a plane primitive.

pxr::UsdGeomPlane usdex::core::definePlane(pxr::UsdPrim parent, const std::string &name, const double width=2.0, const double length=2.0, const pxr::TfToken axis=pxr::UsdGeomTokens->z, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a plane primitive as a child of the parent prim.

pxr::UsdGeomSphere usdex::core::defineSphere(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const double radius=1.0, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a sphere primitive.

pxr::UsdGeomSphere usdex::core::defineSphere(pxr::UsdPrim parent, const std::string &name, const double radius=1.0, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a sphere primitive as a child of the parent prim.

pxr::UsdGeomSphere usdex::core::defineSphere(pxr::UsdPrim prim, const double radius=1.0, const std::optional< pxr::GfVec3f > displayColor=std::nullopt, const std::optional< float > displayOpacity=std::nullopt)

Defines a sphere primitive from an existing prim.

Functions

pxr::UsdGeomCapsule usdex::core::defineCapsule(

pxr::UsdStagePtr stage,

const pxr::SdfPath &path,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a capsule primitive.

Defines a capsule of the specified radius and height at the origin. The height direction can be specified using axis as ‘X’, ‘Y’, or ‘Z’. The total height of the capsule is height + radius + radius.

Parameters:

• stage – The stage on which to define the capsule

• path – The absolute prim path at which to define the capsule

• radius – The radius of the capsule

• height – The height of the capsule shaft, excluding the end caps

• axis – The axis of the capsule

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCapsule schema wrapping the defined UsdPrim

pxr::UsdGeomCapsule usdex::core::defineCapsule(

pxr::UsdPrim parent,

const std::string &name,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a capsule primitive as a child of the parent prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• parent – Prim below which to define the capsule

• name – Name of the capsule

• radius – The radius of the capsule

• height – The height of the capsule shaft, excluding the end caps

• axis – The axis of the capsule

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCapsule schema wrapping the defined UsdPrim

pxr::UsdGeomCapsule usdex::core::defineCapsule(

pxr::UsdPrim prim,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a capsule primitive from an existing prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• prim – Prim below which to define the capsule

• radius – The radius of the capsule

• height – The height of the capsule shaft, excluding the end caps

• axis – The axis of the capsule

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCapsule schema wrapping the defined UsdPrim

pxr::UsdGeomCone usdex::core::defineCone(

pxr::UsdPrim parent,

const std::string &name,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cone primitive as a child of the parent prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• parent – Prim below which to define the cone

• name – Name of the cone

• radius – The radius of the cone

• height – The height of the cone

• axis – The axis of the cone

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCone schema wrapping the defined UsdPrim

pxr::UsdGeomCone usdex::core::defineCone(

pxr::UsdPrim prim,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cone primitive from an existing prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• prim – Prim below which to define the cone

• radius – The radius of the cone

• height – The height of the cone

• axis – The axis of the cone

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCone schema wrapping the defined UsdPrim

pxr::UsdGeomCone usdex::core::defineCone(

pxr::UsdStagePtr stage,

const pxr::SdfPath &path,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cone primitive.

Defines a cone of the specified radius and height at the origin. The height direction can be specified using axis as ‘X’, ‘Y’, or ‘Z’.

Parameters:

• stage – The stage on which to define the cone

• path – The absolute prim path at which to define the cone

• radius – The radius of the cone

• height – The height of the cone

• axis – The axis of the cone

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCone schema wrapping the defined UsdPrim

pxr::UsdGeomCube usdex::core::defineCube(

pxr::UsdPrim prim,

const double size = 2.0,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cube primitive from an existing prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• prim – Prim below which to define the cube

• size – The size of the cube

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCube schema wrapping the defined UsdPrim

pxr::UsdGeomCube usdex::core::defineCube(

pxr::UsdPrim parent,

const std::string &name,

const double size = 2.0,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cube primitive as a child of the parent prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• parent – Prim below which to define the cube

• name – Name of the cube

• size – The size of the cube

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCube schema wrapping the defined UsdPrim

pxr::UsdGeomCube usdex::core::defineCube(

pxr::UsdStagePtr stage,

const pxr::SdfPath &path,

const double size = 2.0,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cube primitive.

Defines a cube of the specified size at the origin.

Note

In order to define a rectangular prism, first call defineCube and then adjust relative scale of each axis using usdex::core::setLocalTransform.

Parameters:

• stage – The stage on which to define the cube

• path – The absolute prim path at which to define the cube

• size – The size of the cube

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCube schema wrapping the defined UsdPrim

pxr::UsdGeomCylinder usdex::core::defineCylinder(

pxr::UsdStagePtr stage,

const pxr::SdfPath &path,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cylinder primitive.

Defines a cylinder of the specified radius and height at the origin. The height direction can be specified using axis as ‘X’, ‘Y’, or ‘Z’.

Parameters:

• stage – The stage on which to define the cylinder

• path – The absolute prim path at which to define the cylinder

• radius – The radius of the cylinder

• height – The height of the cylinder

• axis – The axis of the cylinder

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCylinder schema wrapping the defined UsdPrim

pxr::UsdGeomCylinder usdex::core::defineCylinder(

pxr::UsdPrim prim,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cylinder primitive from an existing prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• prim – Prim below which to define the cylinder

• radius – The radius of the cylinder

• height – The height of the cylinder

• axis – The axis of the cylinder

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCylinder schema wrapping the defined UsdPrim

pxr::UsdGeomCylinder usdex::core::defineCylinder(

pxr::UsdPrim parent,

const std::string &name,

const double radius = 1.0,

const double height = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a cylinder primitive as a child of the parent prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• parent – Prim below which to define the cylinder

• name – Name of the cylinder

• radius – The radius of the cylinder

• height – The height of the cylinder

• axis – The axis of the cylinder

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomCylinder schema wrapping the defined UsdPrim

pxr::UsdGeomPlane usdex::core::definePlane(

pxr::UsdPrim prim,

const double width = 2.0,

const double length = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a plane primitive from an existing prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• prim – Prim below which to define the plane

• width – The width of the plane

• length – The length of the plane

• axis – The axis of the plane

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomPlane schema wrapping the defined UsdPrim

pxr::UsdGeomPlane usdex::core::definePlane(

pxr::UsdStagePtr stage,

const pxr::SdfPath &path,

const double width = 2.0,

const double length = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a plane primitive.

Defines a plane centered at the origin. The normal vector direction can be specified using axis as ‘X’, ‘Y’, or ‘Z’.

While the width and length specify limits for rendering/visualization, it is common to consider the plane as infinite when used as a physics collision in simulation.

Parameters:

• stage – The stage on which to define the plane

• path – The absolute prim path at which to define the plane

• width – The width of the plane

• length – The length of the plane

• axis – The axis of the plane

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomPlane schema wrapping the defined UsdPrim

pxr::UsdGeomPlane usdex::core::definePlane(

pxr::UsdPrim parent,

const std::string &name,

const double width = 2.0,

const double length = 2.0,

const pxr::TfToken axis = pxr::UsdGeomTokens->z,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a plane primitive as a child of the parent prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• parent – Prim below which to define the plane

• name – Name of the plane

• width – The width of the plane

• length – The length of the plane

• axis – The axis of the plane

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomPlane schema wrapping the defined UsdPrim

pxr::UsdGeomSphere usdex::core::defineSphere(

pxr::UsdStagePtr stage,

const pxr::SdfPath &path,

const double radius = 1.0,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a sphere primitive.

Defines a sphere of the specified radius at the origin.

Parameters:

• stage – The stage on which to define the sphere

• path – The absolute prim path at which to define the sphere

• radius – The radius of the sphere

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomSphere schema wrapping the defined UsdPrim

pxr::UsdGeomSphere usdex::core::defineSphere(

pxr::UsdPrim parent,

const std::string &name,

const double radius = 1.0,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a sphere primitive as a child of the parent prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• parent – Prim below which to define the sphere

• name – Name of the sphere

• radius – The radius of the sphere

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomSphere schema wrapping the defined UsdPrim

pxr::UsdGeomSphere usdex::core::defineSphere(

pxr::UsdPrim prim,

const double radius = 1.0,

const std::optional<pxr::GfVec3f> displayColor = std::nullopt,

const std::optional<float> displayOpacity = std::nullopt,

)

Defines a sphere primitive from an existing prim.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

• prim – Prim below which to define the sphere

• radius – The radius of the sphere

• displayColor – Values to be authored for the display color

• displayOpacity – Values to be authored for the display opacity

Returns:

UsdGeomSphere schema wrapping the defined UsdPrim