Camera#
Fully qualified name: isaacsim::foundation::objects::Camera
-
class Camera : public isaacsim::foundation::objects::Xform#
High-level wrapper over one or more USD Camera prims.
Extends Xform with camera-specific attributes: focal length, focus distance, aperture, aperture offset, f-stop, projection type, clipping range, shutter timing, and stereo role. All set/get methods operate in batch over the wrapped prims and accept an optional
indicesparameter to restrict processing to a subset.Public Functions
- Camera(
- const std::variant<std::string, std::vector<std::string>> &paths,
- bool resetXformOpProperties = true,
Construct a Camera wrapper.
- Parameters:
paths – [in] Single path or list of paths to USD Camera prims. May include regular expressions.
resetXformOpProperties – [in] Whether to normalize the xformOp stack to translate/orient/scale.
-
~Camera() = default#
- void setFocalLengths( )#
Set the focal lengths (in scene units) of the selected cameras.
- Parameters:
focalLengths – [in] Focal length values (shape
(N,)). Broadcast rules apply.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array getFocalLengths( )#
Get the focal lengths (in scene units) of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Focal length values (shape
(N,)).
- void setFocusDistances( )#
Set the focus distances (in scene units) of the selected cameras.
- Parameters:
focusDistances – [in] Focus distance values (shape
(N,)). Broadcast rules apply.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array getFocusDistances( )#
Get the focus distances (in scene units) of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Focus distance values (shape
(N,)).
- void setStereoRoles(
- const std::variant<std::string, std::vector<std::string>> &roles,
- const std::optional<array::Array> &indices = std::nullopt,
Set the stereo roles of the selected cameras.
- Parameters:
roles – [in] Stereo role tokens (e.g.
"mono","left","right"). Single value or list; broadcast rules apply.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- std::vector<std::string> getStereoRoles( )#
Get the stereo roles of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Stereo role token strings, one per selected camera.
- void setFStops( )#
Set the f-stop (aperture number) values of the selected cameras.
- Parameters:
fstops – [in] F-stop values (shape
(N,)). Broadcast rules apply.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array getFStops( )#
Get the f-stop (aperture number) values of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
F-stop values (shape
(N,)).
- void setApertures(
- const std::optional<array::Array> &horizontalApertures = std::nullopt,
- const std::optional<array::Array> &verticalApertures = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Set the horizontal and/or vertical aperture sizes (in scene units) of the selected cameras.
- Parameters:
horizontalApertures – [in] Horizontal aperture values (shape
(N,)). Optional.verticalApertures – [in] Vertical aperture values (shape
(N,)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- std::tuple<array::Array, array::Array> getApertures( )#
Get the horizontal and vertical aperture sizes (in scene units) of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
A pair of (horizontalApertures, verticalApertures), each of shape
(N,).
- void setApertureOffsets(
- const std::optional<array::Array> &horizontalOffsets = std::nullopt,
- const std::optional<array::Array> &verticalOffsets = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Set the horizontal and/or vertical aperture offsets (in scene units) of the selected cameras.
- Parameters:
horizontalOffsets – [in] Horizontal aperture offset values (shape
(N,)). Optional.verticalOffsets – [in] Vertical aperture offset values (shape
(N,)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- std::tuple<array::Array, array::Array> getApertureOffsets( )#
Get the horizontal and vertical aperture offsets (in scene units) of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
A pair of (horizontalOffsets, verticalOffsets), each of shape
(N,).
- void setProjections(
- const std::variant<std::string, std::vector<std::string>> &projections,
- const std::optional<array::Array> &indices = std::nullopt,
Set the projection types of the selected cameras.
- Parameters:
projections – [in] Projection type tokens (e.g.
"perspective","orthographic"). Single value or list; broadcast rules apply.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- std::vector<std::string> getProjections( )#
Get the projection types of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Projection type token strings, one per selected camera.
- void setClippingRanges(
- const std::optional<array::Array> &nearDistances = std::nullopt,
- const std::optional<array::Array> &farDistances = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Set the near and/or far clipping plane distances (in scene units) of the selected cameras.
- Parameters:
nearDistances – [in] Near clipping plane distances (shape
(N,)). Optional.farDistances – [in] Far clipping plane distances (shape
(N,)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- std::tuple<array::Array, array::Array> getClippingRanges( )#
Get the near and far clipping plane distances (in scene units) of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
A pair of (nearDistances, farDistances), each of shape
(N,).
- void setShutterTimes(
- const std::optional<array::Array> &openTimes = std::nullopt,
- const std::optional<array::Array> &closeTimes = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Set the shutter open and/or close times of the selected cameras.
- Parameters:
openTimes – [in] Shutter open times relative to the current frame (shape
(N,)). Optional.closeTimes – [in] Shutter close times relative to the current frame (shape
(N,)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- std::tuple<array::Array, array::Array> getShutterTimes( )#
Get the shutter open and close times of the selected cameras.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
A pair of (openTimes, closeTimes), each of shape
(N,).
- void enforceSquarePixels(
- const array::Array &resolutions,
- const std::variant<std::string, std::vector<std::string>> &modes = std::string("horizontal"),
- const std::optional<array::Array> &indices = std::nullopt,
Adjust aperture so that the given pixel resolutions map to square pixels.
Modifies the horizontal or vertical aperture (depending on
modes) to achieve square pixels for the specified output resolutions.- Parameters:
resolutions – [in] Target pixel resolutions as
(height, width) pairs (shape(N,2)).modes – [in] Fitting mode per camera:
"horizontal"adjusts vertical aperture,"vertical"adjusts horizontal aperture. Single value or list.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- void setVisibilities( )#
Set the visibility of the selected prims.
- Parameters:
visibilities – [in] Boolean flags (shape
(N,1)).truemakes a prim visible,falsemakes it invisible. Broadcast rules apply for smaller inputs.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array getVisibilities( )#
Get the visibility state of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating visibility (shape
(N,1)).
- std::tuple<array::Array, array::Array> getWorldPoses(
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Get the world-frame poses (positions and orientations) of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of the returned quaternions:
"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".- Returns:
A pair of (positions, orientations). Positions have shape
(N,3); orientations are quaternions inrotationFormatorder with shape(N,4).
- std::tuple<array::Array, array::Array> getLocalPoses(
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Get the local-frame poses (translations and orientations) of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of the returned quaternions:
"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".- Returns:
A pair of (translations, orientations). Translations have shape
(N,3); orientations are quaternions inrotationFormatorder with shape(N,4).
- array::Array getLocalScales( )#
Get the local scales of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Scale values (shape
(N,3)).
- void setLocalScales( )#
Set the local scales of the selected prims.
- Parameters:
scales – [in] Scale values to apply (shape
(N,3)). Broadcast rules apply for smaller inputs.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- void setLocalPoses(
- const std::optional<array::Array> &translations = std::nullopt,
- const std::optional<array::Array> &orientations = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Set the local-frame poses (translations and/or orientations) of the selected prims.
At least one of
translationsororientationsmust be provided. This method teleports prims to the specified poses.- Parameters:
translations – [in] Local-frame translations (shape
(N,3)). Optional.orientations – [in] Orientations as quaternions in
rotationFormatorder (shape(N,4)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of
orientations:"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".
- void setWorldPoses(
- const std::optional<array::Array> &positions = std::nullopt,
- const std::optional<array::Array> &orientations = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Set the world-frame poses (positions and/or orientations) of the selected prims.
At least one of
positionsororientationsmust be provided. This method teleports prims to the specified poses.- Parameters:
positions – [in] World-frame positions (shape
(N,3)). Optional.orientations – [in] Orientations as quaternions in
rotationFormatorder (shape(N,4)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of
orientations:"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".
-
void resetXformOpProperties()#
Normalize the xformOp stack of all wrapped prims to the standard translate/orient/scale order.
Removes unsupported or redundant xformOp attributes and ensures only
xformOp:translate,xformOp:orient, andxformOp:scaleremain, in that order. World-frame poses are preserved through the normalization.
-
size_t size() const#
Return the number of wrapped prims.
- Returns:
Count of prims managed by this wrapper.
-
const std::vector<std::string> &paths() const#
Return the resolved stage paths of all wrapped prims.
- Returns:
Ordered list of absolute USD stage paths.
-
const Stage &getStage() const#
Return the Stage associated with the wrapped prims.
- Returns:
Reference to the Stage wrapper.
- std::vector<std::string> getName( ) const#
Get the prim names (leaf tokens of each path) for the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of name tokens, one per selected prim.
- std::vector<std::string> getTypeName( ) const#
Get the USD schema type names of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of type name strings, one per selected prim.
- std::vector<std::string> getParent( ) const#
Get the parent prim paths of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of parent path strings, one per selected prim.
- std::vector<std::vector<std::string>> getChildren( ) const#
Get the direct child prim paths of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of child path lists, one list per selected prim.
- std::vector<std::unordered_map<std::string, std::vector<std::string>>> getVariantSets( ) const#
Get the variant sets and their available variants for the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of maps from variant-set name to list of available variant names, one map per selected prim.
- std::vector<std::unordered_map<std::string, std::string>> getVariantSelection( ) const#
Get the active variant selection for each selected prim.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of maps from variant-set name to selected variant name, one map per selected prim.
- void setVariantSelection(
- const std::unordered_map<std::string, std::string> &variants,
- const std::optional<array::Array> &indices = std::nullopt,
Set the active variant selection on the selected prims.
- Parameters:
variants – [in] Map of variant-set name to variant name to activate.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array isA( ) const#
Check whether each selected prim is typed as the given USD schema type.
- Parameters:
schemaType – [in] USD schema type name to test (e.g.
"UsdGeomMesh").indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags (dtype bool, shape
(N,1)), one per selected prim.
- array::Array hasApi(
- const std::string &schemaType,
- const std::optional<std::string> &instanceName = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Check whether each selected prim has the given USD API schema applied.
- Parameters:
schemaType – [in] USD API schema type name.
instanceName – [in] For multi-apply schemas, the instance name to check. Single-apply schemas leave this empty.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags (dtype bool, shape
(N,1)), one per selected prim.
- array::Array applyApi(
- const std::string &schemaType,
- const std::optional<std::string> &instanceName = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Apply a USD API schema to each selected prim.
- Parameters:
schemaType – [in] USD API schema type name.
instanceName – [in] For multi-apply schemas, the instance name to use.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating success (dtype bool, shape
(N,1)), one per selected prim.
- array::Array removeApi(
- const std::string &schemaType,
- const std::optional<std::string> &instanceName = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Remove a USD API schema from each selected prim.
- Parameters:
schemaType – [in] USD API schema type name.
instanceName – [in] For multi-apply schemas, the instance name to remove.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating success (dtype bool, shape
(N,1)), one per selected prim.
- std::vector<std::vector<std::string>> getAppliedSchemas( ) const#
Get the names of all applied API schemas for each selected prim.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of schema name lists, one list per selected prim.
- array::Array createAttribute(
- const std::string &attributeName,
- const std::string &typeName,
- const std::optional<array::Array> &indices = std::nullopt,
Create a custom attribute on each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to create.
typeName – [in] USD value type name (e.g.
"float","double3").indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating whether the attribute was created (dtype bool, shape
(N,1)), one per selected prim.
- array::Array removeAttribute( ) const#
Remove a custom attribute from each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to remove.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating whether the attribute was removed (dtype bool, shape
(N,1)), one per selected prim.
- OutputValueType getAttributeValues( ) const#
Get the values of a named attribute for each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to query.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Attribute values as an
OutputValueTypevariant (string list, nested string list, or numeric array).
- void setAttributeValues(
- const std::string &attributeName,
- const InputValueType &values,
- const std::optional<array::Array> &indices = std::nullopt,
Set the values of a named attribute on each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to set.
values – [in] New attribute values as an
InputValueTypevariant.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
Public Static Functions
- static array::Array areOfType( )#
Check whether the prims at the given paths are of the type handled by this class.
The paths are resolved against the active stage before being checked. Since this method is static, the returned array is always allocated on the CPU.
- Parameters:
paths – [in] Single path string or list of path strings. May include regular expressions that are expanded against the active stage.
- Throws:
std::runtime_error – if the given paths do not correspond to existing prims.
- Returns:
Boolean flags (dtype bool, shape
(N,1)), one per resolved prim.
- static std::tuple<std::vector<std::string>, std::vector<std::string>> resolvePaths( )#
Resolve a path expression against the active stage.
- Parameters:
paths – [in] Single path or list of paths, may include regular expressions.
raiseOnMixedPaths – [in] If
true, throws when existing and non-existing paths are mixed.
- Returns:
A pair of (existing paths, non-existing paths).
Protected Functions
-
void _initialize(bool resetXformOpProperties = false)#
Normalizes the xformOp stack of the wrapped prims when requested.
- std::vector<int64_t> _resolveIndexValues(
- const std::optional<array::Array> &indices,
Converts optional selection indices into signed index values.
- int64_t _resolveIndexedSize(
- const std::optional<array::Array> &indices,
Returns the number of selected prims.