Download OpenAPI specification:
USD Search API is a collection of cloud-native microservices that enable developers, creators, and workflow specialists to efficiently search through vast collections of OpenUSD data, images, and other assets using natural language or image-based inputs. With these production-ready microservices, developers can deploy USD Search API onto their own infrastructure. With USD Search API’s artificial intelligence (AI) features, you can quickly locate untagged and unstructured 3D data and digital assets, saving time navigating unstructured, untagged 3D data. USD Search API is capable of searching and indexing 3D asset databases, as well as navigating complex 3D scenes to perform spatial searches, without requiring manual tagging of assets.
Asset Graph Search (AGS) provides advanced querying capabilities for assets and USD trees indexed in a graph database. It supports proximity queries based on coordinates or prims to find objects within specified areas or radii, sorted by distance, and includes transformation options for vector alignment. The API also offers dependency and reverse dependency searches, helping to identify all assets referenced in a scene or scenes containing a particular asset, which can optimize scene loading and track dependency changes. By combining different query types, the AGS API enables complex scenarios for scene understanding, manipulation, and generation. Integrated with USD Search it provides in-scene search functionality.
Perform a spatial search within a scene to retrieve prims from a USD scene based on their proximity to a reference
prim center_prim_usd_path
or specific coordinates [center_x, center_y, center_z]
within a specified radius
.
Note: You must specify either center_prim_usd_path
or the coordinates [center_x, center_y, center_z]
.
Returns prim objects including: attributes, dimensions, and min, max, midpoint coordinates of the bounding box, distance from the query center, vector from the query center to the prim midpoint.
If searching using center_prim_usd_path
the center prim at center_prim_usd_path
is included in the results
(unless excluded by filters used).
scene_url required | string (Scene Url) URL of the scene to search. |
radius required | number (Radius) Radius of the proximity query |
center_prim_usd_path | string (Center Prim Usd Path) USD path of the reference Prim. (Returned in results unless excluded by filters) |
center_x | number (Center X) X coordinate of the query center. |
center_y | number (Center Y) Y coordinate of the query center. |
center_z | number (Center Z) Z coordinate of the query center. |
transformation_matrix | string (Transformation Matrix) Default: "1,0,0;0,1,0;0,0,1" Transformation matrix for the vector space. By default does not apply any transformation. |
limit | integer (Limit) > 0 Default: 1000 Page size |
Array of Prim Type (strings) or Prim Type (null) (Prim Type) Examples:
Retrieve prims of the specified types. | |
Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix) Examples:
Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path). | |
Properties Filter (string) or Properties Filter (null) (Properties Filter) Examples:
Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: | |
Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X) Minimum bounding box X dimension | |
Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y) Minimum bounding box Y dimension | |
Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z) Minimum bounding box Z dimension | |
Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X) Default: 4e+38 Max bounding box X dimension | |
Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y) Default: 4e+38 Max bounding box Y dimension | |
Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z) Default: 4e+38 Max bounding box Z dimension | |
Use Scaled Bbox Dimensions (boolean) or Use Scaled Bbox Dimensions (null) (Use Scaled Bbox Dimensions) Default: false Search in the space of aligned bbox dimensions |
[- {
- "prim": {
- "scene_url": "string",
- "scene_mpu": 1,
- "usd_path": "string",
- "prim_type": "Xform",
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "translate": [
- 0,
- 0,
- 0
], - "rotate_x": 0,
- "rotate_y": 0,
- "rotate_z": 0,
- "scale_x": 0,
- "scale_y": 0,
- "scale_z": 0,
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "root_prim": true,
- "default_prim": true,
- "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0
}, - "distance": 0,
- "vector": [
- 0
]
}
]
Perform a spatial search within a scene to retrieve prims from a USD scene that fall within a specified bounding box. The bounding box is defined by two points: [min_bbox_x, min_bbox_y, min_bbox_z] and [max_bbox_x, max_bbox_y, max_bbox_z].
A prim is considered to be within the bounding box if its bounding box midpoint falls within the specified query bounding box.
scene_url required | string (Scene Url) Retrieve prims from the scene at specified URL. |
min_bbox_x required | number (Min Bbox X) Query bounding box minimum X |
min_bbox_y required | number (Min Bbox Y) Query bounding box minimum Y |
min_bbox_z required | number (Min Bbox Z) Query bounding box minimum Z |
max_bbox_x required | number (Max Bbox X) Query bounding box maximum X |
max_bbox_y required | number (Max Bbox Y) Query bounding box maximum Y |
max_bbox_z required | number (Max Bbox Z) Query bounding box maximum Z |
limit | integer (Limit) > 0 Default: 1000 Page size |
Array of Prim Type (strings) or Prim Type (null) (Prim Type) Examples:
Retrieve prims of the specified types. | |
Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix) Examples:
Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path). | |
Properties Filter (string) or Properties Filter (null) (Properties Filter) Examples:
Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: | |
Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X) Minimum bounding box X dimension | |
Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y) Minimum bounding box Y dimension | |
Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z) Minimum bounding box Z dimension | |
Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X) Default: 4e+38 Max bounding box X dimension | |
Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y) Default: 4e+38 Max bounding box Y dimension | |
Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z) Default: 4e+38 Max bounding box Z dimension | |
Use Scaled Bbox Dimensions (boolean) or Use Scaled Bbox Dimensions (null) (Use Scaled Bbox Dimensions) Default: false Search in the space of aligned bbox dimensions |
[- {
- "scene_url": "string",
- "scene_mpu": 1,
- "usd_path": "string",
- "prim_type": "Xform",
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "translate": [
- 0,
- 0,
- 0
], - "rotate_x": 0,
- "rotate_y": 0,
- "rotate_z": 0,
- "scale_x": 0,
- "scale_y": 0,
- "scale_z": 0,
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "root_prim": true,
- "default_prim": true,
- "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0
}
]
Retrieve prims from a USD scene.
This API can be used for scene understanding, returns all objects in a scene together with their locations and dimensions.
NOTE: Calling without any parameters will return ALL prims. scene_url
must be provided to fetch prims from the specified scene.
A globally unique prim id consists of (scene_url
, usd_path
) tuple. usd_path
is unique only within a single scene.
To retrieve prims from a specified scene, scene_url
must be set.
To retrieve a single prim from a specified scene, provide both scene_url
and usd_path
.
scene_url | string (Scene Url) Retrieve prims from the scene at specified URL. |
Array of Usd Path (strings) or Usd Path (string) (Usd Path) Examples:
Retrieve prims from the specified USD paths. Can provide either a single path or a list of paths. | |
root_prim | boolean (Root Prim) Retrieve root prims. Note: combined with default_prim returns both root and default prims. Works as inclusive filter only; setting to false has no effect. |
default_prim | boolean (Default Prim) Retrieve default prims. Note: combined with root_prim returns both root and default prims. Works as inclusive filter only; setting to false has no effect. |
source_asset_url | string (Source Asset Url) Filter prims based on their source asset URL, i.e. the asset they have a reference to |
limit | integer (Limit) > 0 Default: 1000 Page size |
Array of Prim Type (strings) or Prim Type (null) (Prim Type) Examples:
Retrieve prims of the specified types. | |
Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix) Examples:
Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path). | |
Properties Filter (string) or Properties Filter (null) (Properties Filter) Examples:
Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: | |
Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X) Minimum bounding box X dimension | |
Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y) Minimum bounding box Y dimension | |
Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z) Minimum bounding box Z dimension | |
Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X) Max bounding box X dimension | |
Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y) Max bounding box Y dimension | |
Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z) Max bounding box Z dimension | |
Use Scaled Bbox Dimensions (boolean) or Use Scaled Bbox Dimensions (null) (Use Scaled Bbox Dimensions) Default: true Search in the space of MPU aligned bbox dimensions |
[- {
- "scene_url": "string",
- "scene_mpu": 1,
- "usd_path": "string",
- "prim_type": "Xform",
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "translate": [
- 0,
- 0,
- 0
], - "rotate_x": 0,
- "rotate_y": 0,
- "rotate_z": 0,
- "scale_x": 0,
- "scale_y": 0,
- "scale_z": 0,
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "root_prim": true,
- "default_prim": true,
- "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0
}
]
Retrieve summary info about a USD scene.
scene_url required | string (Scene Url) Scene summary. |
{- "scene_url": "string",
- "scene_mpu": 0,
- "scene_up_axis": "X",
- "n_prims": 0,
- "prim_types": {
- "property1": 0,
- "property2": 0
}, - "unique_property_keys": {
- "property1": 0,
- "property2": 0
}, - "unique_properties": {
- "property1": 0,
- "property2": 0
}, - "referenced_assets": {
- "property1": 0,
- "property2": 0
}, - "default_prim": {
- "scene_url": "string",
- "scene_mpu": 1,
- "usd_path": "string",
- "prim_type": "Xform",
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "translate": [
- 0,
- 0,
- 0
], - "rotate_x": 0,
- "rotate_y": 0,
- "rotate_z": 0,
- "scale_x": 0,
- "scale_y": 0,
- "scale_z": 0,
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "root_prim": true,
- "default_prim": true,
- "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0
}
}
Get a graph of dependencies (unique files) for the specified asset.
root_node_url required | string (Root Node Url) URL of the asset |
max_level | integer (Max Level) > 0 Max level of dependency tree traversal (by default unlimited) |
limit | integer (Limit) > 0 Default: 1000 Page size |
{- "nodes": [
- {
- "url": "string",
- "deleted": false
}
], - "edges": [
- {
- "node_1_url": "string",
- "node_2_url": "string",
- "type": "depends_on"
}
]
}
Get a flat list of dependencies (unique files) for the specified asset.
root_node_url required | string (Root Node Url) URL of the asset |
max_level | integer (Max Level) > 0 Max level of dependency tree traversal (by default unlimited) |
limit | integer (Limit) > 0 Default: 1000 Page size |
[- {
- "url": "string",
- "deleted": false
}
]
Get a flat list of all assets (unique files) that depend on the specified asset.
root_node_url required | string (Root Node Url) URL of the asset |
max_level | integer (Max Level) > 0 Max level of dependency tree traversal (by default unlimited) |
limit | integer (Limit) > 0 Default: 1000 Page size |
[- {
- "url": "string",
- "deleted": false
}
]
Get a graph of all assets (unique files) that depend on the specified asset.
root_node_url required | string (Root Node Url) URL of the asset |
max_level | integer (Max Level) > 0 Max level of dependency tree traversal (by default unlimited) |
limit | integer (Limit) > 0 Default: 1000 Page size |
{- "nodes": [
- {
- "url": "string",
- "deleted": false
}
], - "edges": [
- {
- "node_1_url": "string",
- "node_2_url": "string",
- "type": "depends_on"
}
]
}
All supported search parameters are available as query parameters.
Search endpoint enables comprehensive searches across images (e.g., .jpg, .png) and USD-based 3D models within various storage backends (Nucleus, S3, etc.). It enables users to use natural language, image similarity, and precise metadata criteria (file name, type, date, size, creator, etc.) to locate relevant content efficiently. Furthermore, when integrated with the Asset Graph Service, USD Search API extends its capabilities to include searches based on USD properties and spatial dimensions of 3D model bounding boxes, enhancing the ability to find assets that meet specific requirements.
description | string (Description) <= 1024 characters Default: "" Examples:
Conduct text-based searches powered by AI |
Array of Image Similarity Search (strings) or Image Similarity Search (null) (Image Similarity Search) Examples:
Perform similarity searches based on a list of images | |
file_name | string (File Name) Default: "" Examples:
Filter results by asset file name, allowing partial matches. Use wildcards: |
exclude_file_name | string (Exclude File Name) Default: "" Examples:
Exclude results by asset file name, allowing partial matches. Use wildcards: |
file_extension_include | string (File Extension Include) Default: "" Examples:
Filter results by file extension. Use wildcards: |
file_extension_exclude | string (File Extension Exclude) Default: "" Examples:
Exclude results by file extension. Use wildcards: |
Created After (string) or Created After (null) (Created After) Examples:
Filter results to only include assets created after a specified date | |
Created Before (string) or Created Before (null) (Created Before) Examples:
Filter results to only include assets created before a specified date | |
Modified After (string) or Modified After (null) (Modified After) Examples:
Filter results to only include assets modified after a specified date | |
Modified Before (string) or Modified Before (null) (Modified Before) Examples:
Filter results to only include assets modified before a specified date | |
File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than) Examples:
Filter results to only include files larger than a specific size | |
File Size Less Than (string) or File Size Less Than (null) (File Size Less Than) Examples:
Filter results to only include files smaller than a specific size | |
created_by | string (Created By) Default: "" Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email. |
exclude_created_by | string (Exclude Created By) Default: "" Examples:
Exclude assets created by a specific user from the results |
modified_by | string (Modified By) Default: "" Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email. |
exclude_modified_by | string (Exclude Modified By) Default: "" Examples:
Exclude assets modified by a specific user from the results |
Similarity Threshold (number) or Similarity Threshold (null) (Similarity Threshold) Examples:
Set the similarity threshold for embedding-based searches. This functionality allows filtering duplicates and returning only those results that are different from each other. Assets are considered to be duplicates if the cosine distance betwen the embeddings a smaller than the similarity_threshold value, which could be in the [0, 2] range. | |
Cutoff Threshold (number) or Cutoff Threshold (null) (Cutoff Threshold) Examples:
Set the cutoff threshold for embedding-based searches | |
search_path | string (Search Path) Default: "" Examples:
Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: |
exclude_search_path | string (Exclude Search Path) Default: "" Examples:
Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: |
Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp) Examples:
Specify an asset URL filter in the Lucene Regexp format. | |
search_in_scene | string (Search In Scene) Default: "" Examples:
Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix. |
filter_by_properties | string (Filter By Properties) Default: "" Examples:
Filter assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: |
exclude_filter_by_properties | string (Exclude Filter By Properties) Default: "" Examples:
Exclude assets by USD attributes (note: only supported for a subset of attributes indexed). Format: |
Min Bbox X (number) or Min Bbox X (null) (Min Bbox X) Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset | |
Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y) Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset | |
Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z) Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox X (number) or Max Bbox X (null) (Max Bbox X) Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y) Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z) Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset | |
return_images | boolean (Return Images) Default: false Return images if set to True |
return_metadata | boolean (Return Metadata) Default: false Return metadata if set to True |
return_root_prims | boolean (Return Root Prims) Default: false Return root prims if set to True |
return_default_prims | boolean (Return Default Prims) Default: false Return default prims if set to True |
return_predictions | boolean (Return Predictions) Deprecated Default: false Returns predictions for each asset in the search results from the fixed vocabulary. NOTE: This functionality is deprecated and setting this parameter will have no effect starting from USD Search version API 1.3. This parameter will be completely removed from the list of input parameters in USD Search API version 2 and above. Please rely on VLM-based auto-captioning functionality instead. |
return_in_scene_instances_prims | boolean (Return In Scene Instances Prims) Default: false [in-scene search only] Return prims of instances of objects found in the scene |
SearchMethod (string) or Embedding Knn Search Method (null) (Embedding Knn Search Method) Search method, approximate should be faster but is less accurate. Default is exact | |
Limit (integer) or Limit (null) (Limit) Set the maximum number of results to return from the search, default is 32 | |
Vision Metadata (string) or Vision Metadata (null) (Vision Metadata) Uses a keyword match query on metadata fields that were generated using Vision Language Models | |
return_vision_generated_metadata | boolean (Return Vision Generated Metadata) Default: false Returns the metadata fields that were generated using Vision Language Models |
return_inner_hits | boolean (Return Inner Hits) Default: false Return inner hits from nested queries for debugging and detailed scoring |
[- {
- "url": "omniverse://sample-nucleus-server.example.com/Projects/sample-usd-asset.usd",
- "score": 1.2529583,
- "root_prims": [
- {
- "scene_url": "omniverse://sample-nucleus-server.example.com/Projects/sample-usd-asset.usd",
- "usd_path": "/RootNode",
- "prim_type": "Xform",
- "bbox_max": [
- 0.34971755743026733,
- 0.2549635171890259,
- 0.5211517214775085
], - "bbox_min": [
- -0.34971755743026733,
- -0.25496378540992737,
- 1.9483268332010084e-8
], - "bbox_midpoint": [
- 0,
- -1.341104507446289e-7,
- 0.26057587048038844
], - "bbox_dimension_x": 0.6994351148605347,
- "bbox_dimension_y": 0.5099273025989532,
- "bbox_dimension_z": 0.5211517019942402,
- "properties": {
- "semantic:QWQQ:params:semanticData": "Q1395006",
- "semantic:QWQL:params:semanticType": "class",
- "semantic:QWQQ:params:semanticType": "qcode",
- "semantic:QWQC:params:semanticData": "container/product packaging/box/cardboard box",
- "semantic:QWQL:params:semanticData": "cardboard box",
- "semantic:QWQC:params:semanticType": "hierarchy"
}
}
], - "metadata": {
- "created": "Mon Mar 20 22:06:58 2023",
- "created_by": "user@nvidia.com",
- "modified": "Mon Mar 20 22:06:58 2023",
- "modified_by": "user@nvidia.com",
- "size": 14938,
- "etag": "169176"
}, - "vision_generated_metadata": {
- "vision_generated_object_type": "electric guitar, musical instrument, guitar",
- "vision_generated_materials": "wood, metal, plastic"
}
}
]
All supported search parameters are available as body parameters.
Search endpoint enables comprehensive searches across images (e.g., .jpg, .png) and USD-based 3D models within various storage backends (Nucleus, S3, etc.). It enables users to use natural language, image similarity, and precise metadata criteria (file name, type, date, size, creator, etc.) to locate relevant content efficiently. Furthermore, when integrated with the Asset Graph Service, USD Search API extends its capabilities to include searches based on USD properties and spatial dimensions of 3D model bounding boxes, enhancing the ability to find assets that meet specific requirements.
Description (string) or Description (null) (Description) Conduct text-based searches powered by AI | |
Array of Image Similarity Search (strings) or Image Similarity Search (null) (Image Similarity Search) Perform similarity searches based on images | |
File Name (string) or File Name (null) (File Name) Filter results by asset file name, allowing partial matches. Use wildcards: | |
Exclude File Name (string) or Exclude File Name (null) (Exclude File Name) Exclude results by asset file name, allowing partial matches. Use wildcards: | |
File Extension Include (string) or File Extension Include (null) (File Extension Include) Filter results by file extension. Use wildcards: | |
File Extension Exclude (string) or File Extension Exclude (null) (File Extension Exclude) Exclude results by file extension. Use wildcards: | |
Created After (string) or Created After (null) (Created After) Filter results to only include assets created after a specified date | |
Created Before (string) or Created Before (null) (Created Before) Filter results to only include assets created before a specified date | |
Modified After (string) or Modified After (null) (Modified After) Filter results to only include assets modified after a specified date | |
Modified Before (string) or Modified Before (null) (Modified Before) Filter results to only include assets modified before a specified date | |
File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than) Filter results to only include files larger than a specific size | |
File Size Less Than (string) or File Size Less Than (null) (File Size Less Than) Filter results to only include files smaller than a specific size | |
Created By (string) or Created By (null) (Created By) Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email. | |
Exclude Created By (string) or Exclude Created By (null) (Exclude Created By) Exclude assets created by a specific user from the results | |
Modified By (string) or Modified By (null) (Modified By) Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email. | |
Exclude Modified By (string) or Exclude Modified By (null) (Exclude Modified By) Exclude assets modified by a specific user from the results | |
Similarity Threshold (number) or Similarity Threshold (null) (Similarity Threshold) Set the similarity threshold for embedding-based searches. This functionality allows filtering duplicates and returning only those results that are different from each other. Assets are considered to be duplicates if the cosine distance betwen the embeddings a smaller than the similarity_threshold value, which could be in the [0, 2] range. | |
Cutoff Threshold (number) or Cutoff Threshold (null) (Cutoff Threshold) Set the cutoff threshold for embedding-based searches | |
Search Path (string) or Search Path (null) (Search Path) Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: | |
Exclude Search Path (string) or Exclude Search Path (null) (Exclude Search Path) Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: | |
Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp) Specify an asset URL filter in the Lucene Regexp format. | |
Search In Scene (string) or Search In Scene (null) (Search In Scene) Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix. | |
Filter By Properties (string) or Filter By Properties (null) (Filter By Properties) Filter assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: | |
Min Bbox X (number) or Min Bbox X (null) (Min Bbox X) Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset | |
Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y) Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset | |
Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z) Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox X (number) or Max Bbox X (null) (Max Bbox X) Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y) Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z) Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset | |
bbox_use_scaled_dimensions | boolean (Bbox Use Scaled Dimensions) Default: true Use scaled dimensions for bounding box filtering |
return_images | boolean (Return Images) Default: false Return images if set to True |
return_metadata | boolean (Return Metadata) Default: false Return metadata if set to True |
return_root_prims | boolean (Return Root Prims) Default: false Return root prims if set to True |
return_default_prims | boolean (Return Default Prims) Default: false Return default prims if set to True |
return_predictions | boolean (Return Predictions) Default: false Return predictions if set to True |
return_in_scene_instances_prims | boolean (Return In Scene Instances Prims) Default: false [in-scene search only] Return prims of instances of objects found in the scene |
SearchMethod (string) or null Search method, approximate should be faster but is less accurate. Default is exact | |
Limit (integer) or Limit (null) (Limit) Default: 32 Set the maximum number of results to return from the search, default is 32 | |
Vision Metadata (string) or Vision Metadata (null) (Vision Metadata) Uses a keyword match query on metadata fields that were generated using Vision Language Models. Format: | |
return_vision_generated_metadata | boolean (Return Vision Generated Metadata) Default: false Returns the metadata fields that were generated using Vision Language Models |
return_inner_hits | boolean (Return Inner Hits) Default: false Return inner hits from nested queries |
ScoringConfig (object) or null Configuration for field scoring | |
Hybrid Text Query (string) or Hybrid Text Query (null) (Hybrid Text Query) Query for hybrid text search across multiple fields | |
Array of objects (Vector Queries) Generic vector queries for different fields | |
return_embeddings | boolean (Return Embeddings) Default: false Return embeddings for search results |
return_tags | boolean (Return Tags) Default: false Return tags for search results |
return_usd_properties | boolean (Return Usd Properties) Default: false Return USD properties for search results |
return_usd_dimensions | boolean (Return Usd Dimensions) Default: false Return USD dimensions for search results |
deduplicate_by_hash | boolean (Deduplicate By Hash) Default: false Return only items with unique hash_value using OpenSearch collapse |
{- "hybrid_text_query": "red car vehicle",
- "limit": 10,
- "return_images": true,
- "return_metadata": true,
- "vector_queries": [
- {
- "field_name": "clip-embedding.embedding",
- "query": "red car vehicle",
- "query_type": "text"
}
]
}
[- {
- "url": "omniverse://sample-nucleus-server.example.com/Projects/sample-usd-asset.usd",
- "score": 1.2529583,
- "root_prims": [
- {
- "scene_url": "omniverse://sample-nucleus-server.example.com/Projects/sample-usd-asset.usd",
- "usd_path": "/RootNode",
- "prim_type": "Xform",
- "bbox_max": [
- 0.34971755743026733,
- 0.2549635171890259,
- 0.5211517214775085
], - "bbox_min": [
- -0.34971755743026733,
- -0.25496378540992737,
- 1.9483268332010084e-8
], - "bbox_midpoint": [
- 0,
- -1.341104507446289e-7,
- 0.26057587048038844
], - "bbox_dimension_x": 0.6994351148605347,
- "bbox_dimension_y": 0.5099273025989532,
- "bbox_dimension_z": 0.5211517019942402,
- "properties": {
- "semantic:QWQQ:params:semanticData": "Q1395006",
- "semantic:QWQL:params:semanticType": "class",
- "semantic:QWQQ:params:semanticType": "qcode",
- "semantic:QWQC:params:semanticData": "container/product packaging/box/cardboard box",
- "semantic:QWQL:params:semanticData": "cardboard box",
- "semantic:QWQC:params:semanticType": "hierarchy"
}
}
], - "metadata": {
- "created": "Mon Mar 20 22:06:58 2023",
- "created_by": "user@nvidia.com",
- "modified": "Mon Mar 20 22:06:58 2023",
- "modified_by": "user@nvidia.com",
- "size": 14938,
- "etag": "169176"
}, - "vision_generated_metadata": {
- "vision_generated_object_type": "electric guitar, musical instrument, guitar",
- "vision_generated_materials": "wood, metal, plastic"
}
}
]
Get statistics for USD properties: count of unique properties, count of unique values, and count of unique kv pairs.
{- "unique_keys": [
- {
- "key": "string",
- "asset_count": 0
}
], - "unique_values": [
- {
- "value": "string",
- "asset_count": 0
}
], - "kv_pairs": [
- {
- "key": "string",
- "value": "string",
- "asset_count": 0
}
]
}
Hybrid Search endpoint is an evolution of basic /search endpoint that supports the same filters but returns data in a new format and adds support for the following features:
Description (string) or Description (null) (Description) Conduct text-based searches powered by AI | |
Array of Image Similarity Search (strings) or Image Similarity Search (null) (Image Similarity Search) Perform similarity searches based on images | |
File Name (string) or File Name (null) (File Name) Filter results by asset file name, allowing partial matches. Use wildcards: | |
Exclude File Name (string) or Exclude File Name (null) (Exclude File Name) Exclude results by asset file name, allowing partial matches. Use wildcards: | |
File Extension Include (string) or File Extension Include (null) (File Extension Include) Filter results by file extension. Use wildcards: | |
File Extension Exclude (string) or File Extension Exclude (null) (File Extension Exclude) Exclude results by file extension. Use wildcards: | |
Created After (string) or Created After (null) (Created After) Filter results to only include assets created after a specified date | |
Created Before (string) or Created Before (null) (Created Before) Filter results to only include assets created before a specified date | |
Modified After (string) or Modified After (null) (Modified After) Filter results to only include assets modified after a specified date | |
Modified Before (string) or Modified Before (null) (Modified Before) Filter results to only include assets modified before a specified date | |
File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than) Filter results to only include files larger than a specific size | |
File Size Less Than (string) or File Size Less Than (null) (File Size Less Than) Filter results to only include files smaller than a specific size | |
Created By (string) or Created By (null) (Created By) Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email. | |
Exclude Created By (string) or Exclude Created By (null) (Exclude Created By) Exclude assets created by a specific user from the results | |
Modified By (string) or Modified By (null) (Modified By) Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email. | |
Exclude Modified By (string) or Exclude Modified By (null) (Exclude Modified By) Exclude assets modified by a specific user from the results | |
Similarity Threshold (number) or Similarity Threshold (null) (Similarity Threshold) Set the similarity threshold for embedding-based searches. This functionality allows filtering duplicates and returning only those results that are different from each other. Assets are considered to be duplicates if the cosine distance betwen the embeddings a smaller than the similarity_threshold value, which could be in the [0, 2] range. | |
Cutoff Threshold (number) or Cutoff Threshold (null) (Cutoff Threshold) Set the cutoff threshold for embedding-based searches | |
Search Path (string) or Search Path (null) (Search Path) Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: | |
Exclude Search Path (string) or Exclude Search Path (null) (Exclude Search Path) Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: | |
Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp) Specify an asset URL filter in the Lucene Regexp format. | |
Search In Scene (string) or Search In Scene (null) (Search In Scene) Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix. | |
Filter By Properties (string) or Filter By Properties (null) (Filter By Properties) Filter assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: | |
Min Bbox X (number) or Min Bbox X (null) (Min Bbox X) Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset | |
Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y) Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset | |
Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z) Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox X (number) or Max Bbox X (null) (Max Bbox X) Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y) Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset | |
Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z) Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset | |
bbox_use_scaled_dimensions | boolean (Bbox Use Scaled Dimensions) Default: true Use scaled dimensions for bounding box filtering |
return_images | boolean (Return Images) Default: false Return images if set to True |
return_metadata | boolean (Return Metadata) Default: false Return metadata if set to True |
return_root_prims | boolean (Return Root Prims) Default: false Return root prims if set to True |
return_default_prims | boolean (Return Default Prims) Default: false Return default prims if set to True |
return_predictions | boolean (Return Predictions) Default: false Return predictions if set to True |
return_in_scene_instances_prims | boolean (Return In Scene Instances Prims) Default: false [in-scene search only] Return prims of instances of objects found in the scene |
SearchMethod (string) or null Search method, approximate should be faster but is less accurate. Default is exact | |
Limit (integer) or Limit (null) (Limit) Default: 32 Set the maximum number of results to return from the search, default is 32 | |
Vision Metadata (string) or Vision Metadata (null) (Vision Metadata) Uses a keyword match query on metadata fields that were generated using Vision Language Models. Format: | |
return_vision_generated_metadata | boolean (Return Vision Generated Metadata) Default: false Returns the metadata fields that were generated using Vision Language Models |
return_inner_hits | boolean (Return Inner Hits) Default: false Return inner hits from nested queries |
ScoringConfig (object) or null Configuration for field scoring | |
Hybrid Text Query (string) or Hybrid Text Query (null) (Hybrid Text Query) Query for hybrid text search across multiple fields | |
Array of objects (Vector Queries) Generic vector queries for different fields | |
return_embeddings | boolean (Return Embeddings) Default: false Return embeddings for search results |
return_tags | boolean (Return Tags) Default: false Return tags for search results |
return_usd_properties | boolean (Return Usd Properties) Default: false Return USD properties for search results |
return_usd_dimensions | boolean (Return Usd Dimensions) Default: false Return USD dimensions for search results |
deduplicate_by_hash | boolean (Deduplicate By Hash) Default: false Return only items with unique hash_value using OpenSearch collapse |
{- "hybrid_text_query": "red car vehicle",
- "vector_queries": [
- {
- "field_name": "clip-embedding.embedding",
- "query_type": "text",
- "query": "red car vehicle"
}
], - "return_metadata": true,
- "return_images": true,
- "limit": 10
}
{- "total": 0,
- "hits": [
- {
- "id": "string",
- "score": 0,
- "rrf_score": 0,
- "metadata": {
- "explanations": [
- {
- "search_type": "text",
- "score": 0,
- "field": "string",
- "details": { },
- "rrf_score": 0,
- "rrf_rank_constant": 0,
- "matched_terms": [
- "string"
], - "vector_similarity": 0,
- "matched_vectors": [
- {
- "offset": 0,
- "score": 0,
- "field": "string",
- "image": "string",
- "keyword": [
- "string"
], - "label": "string"
}
]
}
], - "rrf_rank": 0,
- "original_ranks": {
- "property1": 0,
- "property2": 0
}
}, - "source": { },
- "inner_hits": { },
- "ags_data": {
- "instance_prims": [
- {
- "scene_url": "string",
- "scene_mpu": 0,
- "usd_path": "string",
- "prim_type": "string",
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0,
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "root_prim": true,
- "default_prim": true
}
], - "root_prims": [
- {
- "scene_url": "string",
- "scene_mpu": 0,
- "usd_path": "string",
- "prim_type": "string",
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0,
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "root_prim": true,
- "default_prim": true
}
], - "default_prims": [
- {
- "scene_url": "string",
- "scene_mpu": 0,
- "usd_path": "string",
- "prim_type": "string",
- "bbox_max": [
- 0
], - "bbox_min": [
- 0
], - "bbox_midpoint": [
- 0
], - "bbox_dimension_x": 0,
- "bbox_dimension_y": 0,
- "bbox_dimension_z": 0,
- "scaled_bbox_dimension_x": 0,
- "scaled_bbox_dimension_y": 0,
- "scaled_bbox_dimension_z": 0,
- "source_asset_url": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "root_prim": true,
- "default_prim": true
}
]
}, - "thumbnail_exists": true
}
], - "search_metadata": { }
}
For each URL the service checks caches of all plugins that support processing this asset and reports the following information:
indexing_status [not_found / in_sync / out_of_sync ] - this parameter checks the difference between cached value of asset hash and the actual (up-to-date) asset hash from the storage backend.
plugin_status_history - is a list of last statuses that were assigned to the asset, while it was being processed. Each item of this list has the following structure:
status [ok / processing / failed_retries_exhausted / other string] - shows whether the asset was
processing_timestamp - the moment when the status was assigned
exception - optional exception explanation
The service could additionally report asset metadata from the storage backend if return_asset_metadata flag is set to True.
url required | string (Url) Asset URL for which processing status needs to be retrieved |
return_asset_metadata | boolean (Return Asset Metadata) Default: false Return metadata for the asset if set to True |
{- "url": "string",
- "plugins_statuses": {
- "property1": {
- "indexing_status": "in_sync",
- "indexed_asset_hash": "string",
- "plugin_status_history": [
- {
- "status": "string",
- "hash_value": "string",
- "processing_timestamp": 0,
- "exception": "string"
}
]
}, - "property2": {
- "indexing_status": "in_sync",
- "indexed_asset_hash": "string",
- "plugin_status_history": [
- {
- "status": "string",
- "hash_value": "string",
- "processing_timestamp": 0,
- "exception": "string"
}
]
}
}, - "storage_backend_info": {
- "asset_status": "ok",
- "storage_asset_hash": "string",
- "metadata": {
- "uri": "string",
- "etag": "string",
- "status": "string",
- "event": "acl_change",
- "type": "string",
- "ts": {
- "property1": 0,
- "property2": 0
}, - "transaction_id": "string",
- "acl": [
- "string"
], - "empty": true,
- "mounted": true,
- "size": 0,
- "created_by": "string",
- "created_date_seconds": 0,
- "modified_by": "string",
- "modified_date_seconds": 0,
- "hash_type": "string",
- "hash_value": "string",
- "hash_bsize": 0,
- "is_deleted": true,
- "deleted_by": "string",
- "deleted_date_seconds": 0
}
}
}
USD Search processes all assets on the storage backend in the background. This, however, may take time depending on the amount of data on the storage backend and the amount of available resources, which could lead to delays in specific assets appearing in the search index. In order to address this and prioritize processing of specific assets, it is possible to use this endpoint to trigger indexing of a specific asset on demand.
When triggering processing of a specific asset URL the user could decide, with which plugin the asset needs to be processed. By default, when no plugin is selected - the service will trigger processing for all plugins that could work with this asset type. Please find below the list of supported plugins:
asset_graph_generation: Constructs several graphs based on the prim hierarchy of a USD file. This plugin is an essential component of Asset Graph Service (AGS).
image_to_embedding: Extracts CLIP embeddings from the images that are found on the storage backend.
image_to_vision_metadata: Extracts VLM-generated metadata from the images that are found on the storage backend.
rendering_to_embedding: Renders the asset and extracts CLIP embeddings from the generated preview images.
rendering_to_vision_metadata: Renders the asset and extracts VLM-generated metadata using the generated preview images.
thumbnail_generation: Renders the asset uploads one of the rendered images to the storage backend to serve as a thumbnail for this asset.
thumbnail_to_embedding: For any asset stored on the storage backend this plugin relies on the thumbnail of this asset to extract CLIP embeddings.
thumbnail_to_vision_metadata: For any asset stored on the storage backend this plugin relies on the thumbnail of this asset to extract VLM-generated metadata.
NOTE: If some of the plugins are not enabled for the USD Search instance, selecting them for the plugins parameter setting will have not effect. Please reach out to your USD Search service administrator if you would like to enable certain plugin functionality. The list of plugins that are enabled for this USD Search instance could be retrieved using /info/plugins endpoint.
url required | string (Url) Asset URL which should be submitted for priority processing |
Array of Plugins (strings) or Plugins (null) (Plugins) List of plugins for which indexing needs to be re-done | |
refresh_metadata | boolean (Refresh Metadata) Default: false refresh asset metadata |
refresh_tags | boolean (Refresh Tags) Default: false refresh asset tags |
JobItemType (string) or Priority (string) or Priority (null) (Priority) Default: "priority" processing job type |
null
Display some information about the storage backend, to which the USD Search API instance is connected to.
check_availability | boolean (Check Availability) Default: false Check if storage backend is available |
{- "backends": {
- "property1": {
- "storage_backend_type": "nucleus",
- "base_url": "string",
- "s3_endpoint_url": "string",
- "available": true
}, - "property2": {
- "storage_backend_type": "nucleus",
- "base_url": "string",
- "s3_endpoint_url": "string",
- "available": true
}
}
}
Get the list of plugins that are supported by the USD Search instance
only_active | boolean (Only Active) Default: true show only active plugins |
[- {
- "name": "string",
- "description": "string",
- "data_types": [
- "string"
], - "requires_rendering": true,
- "active": true,
- "config": { }
}
]
Fetch image binary data for a specific asset by URL or direct image key lookup
Asset Url (string) or Asset Url (null) (Asset Url) The complete URL of the asset to fetch image data for. Must be a valid asset URL that the user has access to. | |
Image Key (string) or Image Key (null) (Image Key) Direct image key/ID to fetch from OpenSearch. Use this for direct image retrieval when you already know the image identifier. | |
img_offset | integer (Img Offset) >= 0 Default: 0 Zero-based index specifying which image to fetch from the asset's clip-embeddings. Only valid when using asset_url. |
null